A Hexo plugins which helps to introduce low quality image placeholders to the theme
Last updated 3 days ago by ertrzyiks .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install hexo-filter-lqip 
SYNC missed versions from official npm registry.


A Hexo plugins which helps to introduce low quality image placeholders to the theme


npm i hexo-filter-lqip --save


Install this plugin for the theme and use the view helper to render a placeholder.

lqipFor view helper

lqipFor(path_to_asset, options)
  • String *path_to_asset - a path to the image
  • Object options
    • String [type] - a type of placeholder, see the list of available types, defaults to the default_type as configured

Returns a CSS value for background-image property, which is a simplified version of the original image.

Example for EJS

  style="background-image: <%- lqip_for('/content/my-photo.jpg') %>"

Front-end integration

To make it work as a real placeholder, there must be a piece of JavaScript code, which will eventually replace the placeholder with the original image. It can be done by adding a data attribute with the original image path:

  style="background-image: <%- lqip_for('/content/my-photo.jpg') %>"

and replacing the background-image CSS property with the original image once it's loaded:

(function () {
  var lazyImages = document.querySelectorAll('[data-lazy-src]')

  lazyImages.forEach(function (img) {
    var url = img.dataset.lazySrc
    var image = new Image()
    image.onload = function () {
      img.style.backgroundImage = 'url(' + url + ')'
    image.src = url

For even more improvement, the script could load only images that are visible on the screen.

Available types


Type name: potrace

Uses the posterize function from potrace to generate simplified SVG version of the image. The output is optimized with SVGO and inlined.


Type name: color

Plain background, the dominant color extracted from the image.


Put your configuration in the theme _config.yml under lqip key. You can also use the overriding theme config feature of Hexo. Available options are the following:


Defaults to 'lqip-cache.json'. Could be a string with a file name of the cache. You can also set to false to disable caching.

Ideally, the cache file should not be checked in into repository.


The priority of the after_generate filter. Defaults to 10. You can find more information about priority in Filter documentation.


Defaults to potrace. Use this type if not specified as a param to lqip_for helper.


Configuration specific to potrace type. All keys except canvas_size are passed to the posterize function of potrace

canvas_size: {width:, height:}

Before the image is passed to potrace, it's resized to this size.

Example configuration:

  default_type: potrace
      width: 140
    steps: 2
    color: '#dedede'
    background: transparent


If something goes wrong, use --debug option to get all information about the generating of the blog and extra information about low-quality image placeholders processing.

hexo generate --debug

After changing parameters of placeholder it may be required to clean cache, by removing the cache file manually or with:

hexo clean

Example project

You can see it put together in the hexo-lqip-example repository.

Out there in the wild


Current Tags

  • 1.4.1                                ...           latest (3 days ago)

10 Versions

  • 1.4.1                                ...           3 days ago
  • 1.4.0                                ...           a year ago
  • 1.3.3                                ...           a year ago
  • 1.3.2                                ...           a year ago
  • 1.3.1                                ...           2 years ago
  • 1.3.0                                ...           2 years ago
  • 1.2.0                                ...           2 years ago
  • 1.1.1                                ...           3 years ago
  • 1.1.0                                ...           3 years ago
  • 1.0.0                                ...           3 years ago
Today 0
This Week 1
This Month 12
Last Day 1
Last Week 11
Last Month 1
Dependencies (7)
Dev Dependencies (6)
Dependents (0)

Copyright 2014 - 2016 © taobao.org |