Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


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 () { = '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