Lazy image loader and utilities for Symfony

Installs: 5 928

Dependents: 0

Suggesters: 0

Security: 0

Stars: 13

Watchers: 5

Forks: 2


v1.3.0 2021-04-05 13:47 UTC

This package is auto-updated.

Last update: 2021-09-22 08:27:09 UTC


Symfony UX LazyImage is a Symfony bundle providing utilities to improve image loading performance. It is part of the Symfony UX initiative.

It provides two key features:

  • a Stimulus controller to load lazily heavy images, with a placeholder
  • a BlurHash implementation to create data-uri thumbnails for images


Symfony UX LazyImage requires PHP 7.2+ and Symfony 4.4+.

You can install this bundle using Composer and Symfony Flex:

composer require symfony/ux-lazy-image

# Don't forget to install the JavaScript dependencies as well and compile
yarn install --force
yarn encore dev

Also make sure you have at least version 2.0 of @symfony/stimulus-bridge in your package.json file.


The default usage of Symfony UX LazyImage is to use its Stimulus controller to first load a small placeholder image that will then be replaced by the high-definition version once the page has been rendered:

    src="{{ asset('image/small.png') }}"
    {{ stimulus_controller('symfony/ux-lazy-image/lazy-image') }}
    data-hd-src="{{ asset('image/large.png') }}"

    {# Optional but avoids having a page jump when the image is loaded #}

Note The stimulus_controller() function comes from WebpackEncoreBundle v1.10.

Instead of using a generated thumbnail that would exist on your filesystem, you can use the BlurHash algorithm to create a light, blurred, data-uri thumbnail of the image:

    src="{{ data_uri_thumbnail('public/image/large.png', 100, 75) }}"
    {{ stimulus_controller('symfony/ux-lazy-image/lazy-image') }}
    data-hd-src="{{ asset('image/large.png') }}"

    {# Using BlurHash, the size is required #}

The data_uri_thumbnail function receives 3 arguments:

  • the server path to the image to generate the data-uri thumbnail for ;
  • the width of the BlurHash to generate
  • the height of the BlurHash to generate

You should try to generate small BlurHash images as generating the image can be CPU-intensive. Instead, you can rely on the browser scaling abilities by generating a small image and using the width and height HTML attributes to scale up the image.

Extend the default behavior

Symfony UX LazyImage allows you to extend its default behavior using a custom Stimulus controller:

// mylazyimage_controller.js

import { Controller } from 'stimulus';

export default class extends Controller {
    connect() {
        this.element.addEventListener('lazy-image:connect', this._onConnect);
        this.element.addEventListener('lazy-image:ready', this._onReady);

    disconnect() {
        // You should always remove listeners when the controller is disconnected to avoid side-effects
        this.element.removeEventListener('lazy-image:connect', this._onConnect);
        this.element.removeEventListener('lazy-image:ready', this._onReady);

    _onConnect(event) {
        // The lazy-image behavior just started

    _onReady(event) {
        // The HD version has just been loaded

Then in your template, add your controller to the HTML attribute:

    src="{{ data_uri_thumbnail('public/image/large.png', 100, 75) }}"
    {{ stimulus_controller({
        mylazyimage: {},
        'symfony/ux-lazy-image/lazy-image: {}
    }) }}
    data-hd-src="{{ asset('image/large.png') }}"

    {# Using BlurHash, the size is required #}

Note: be careful to add your controller before the LazyImage controller so that it is executed before and can listen on the lazy-image:connect event properly.

Backward Compatibility promise

This bundle aims at following the same Backward Compatibility promise as the Symfony framework:

However it is currently considered experimental, meaning it is not bound to Symfony's BC policy for the moment.

Run tests

PHP tests

php vendor/bin/phpunit

JavaScript tests

cd Resources/assets
yarn test