django-lazy-srcset 1.0.2

Lazy srcset and responsive image generation for Django. Minimum effort required. No database required.

Django Lazy srcset

Lazy srcset and responsive image generation for Django. Minimum effort required. No database required.

Django Lazy srcset will create the markup and generate the images you need to provide responsive images via the srcset and sizes attributes for the img tag. All you need to do is install it, configure your breakpoints and use the {% srcset %} template tag.

All of the hard work (image generation and cacheing) is done by django-imagekit, by default this means images are generated just in time - lazily. Please see the django-imagekit docs for more info and configuration options.

Width and height attributes are generated to help avoid layout shifts. Make sure you set these in CSS so they are only used by the browser for aspect ratio.

SVG images are supported, they will not be converted or resized but width and height attributes are still added as well as the role="img" attribute.

You will also need Django and Pillow.

Installation & Usage

Install with pip:

$ pip install django-lazy-srcset

Add "imagekit" and "lazy_srcset" to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "imagekit",
    "lazy_srcset",
    # ...
]

Configure your breakpoints and stuff (most/all of this is optional):

# When disabled src, width and height attributes are returned so images still work but no srcset or image
# generation will happen. By default, lazy-srcset is disabled when debug is True.
LAZY_SRCSET_ENABLED = not django_settings.DEBUG

# The default threshold to use when not specified in the config.
LAZY_SRCSET_THRESHOLD = 69

# The default generator to use when not specified in the config.
LAZY_SRCSET_GENERATOR_ID = "lazy_srcset:srcset_image"

LAZY_SRCSET = {
    "default": {
        # breakpoints is the only setting you must define
        "breakpoints": [1920, 1580, 1280, 1024, 640],
        # If max_width is not provided the source image width is used.
        # It's a good idea to set this.
        "max_width": 2560,
        # If quality is not provided PIL will choose a default
        "quality": 91,
        # If format is not provided the source image format is used
        "format": "WEBP",
        # The difference in width (px) required to generate a new image
        # This prevents images being created which are too similar in size
        "threshold": LAZY_SRCSET_THRESHOLD,
        # If generator_id is not provided LAZY_SRCSET_GENERATOR_ID is used
        "generator_id": LAZY_SRCSET_GENERATOR_ID,
    }
}

Use the {% srcset %} template tag:

{% load lazy_srcset %}

{# image is an ImageField. With no args or kwargs provided all sizes are assumed to be 100vw #}
<img {% srcset image %} alt="Lovely and lazy" />

{# You can provide a path to a static file instead of an ImageField. #}
<img {% srcset 'path/to/my/image.png' %} />

{# You can provide relative (vw) image widths e.g. for a 4 - 3 - 2 - 1 col degradation #}
{# These are used to calculate the width of the generated images for each breakpoint #}
<img {% srcset image 25 33 50 %}  />

{# Kwargs can be used to define breakpoints and some settings #}
<img {% srcset image 1920=25 1580=33 1024=50 640=100 max_width=1920 %} />

{# Fixed width images can be defined with px units. These are always made regardless of threshold #}
<img {% srcset image '500px' '400px' '300px' %} />

Whilst not required it is advisable to take a nap at this stage.

For further documentation and examples of all the options please see the huge and obvious docstring in the source code for lazy_srcset/templatetags/lazy_srcset.py.

How it Works

If the source image is wider than the max_width it is resized to max_width. Otherwise it is converted as is. This image is then used in the srcset and src attributes.

For each breakpoint we calculate the target width of the image required and iterate from biggest to smallest. Images are then generated if the required width is:

• Smaller than the source width (no upscaling!).

• Smaller than the previously generated image by more than threshold px unless the size was defined with px units.

Once imagekit has generated an image it won’t create it again and it will store this fact in the cache to further speed up subsequent renders.

Advanced

Due to the awesomeness of django-imagekit it’s possible to configure django-lazy-srcset to use any image generator you have registered on a per config basis. Take a look at lazy_srcset/conf.py to see how to change the generator_id setting. For an example image generator look at lazy_srcset/imagegenerators.py. This is completely optional but I thought I’d mention it as there are potential artistic uses here; for example you could use a generator to add filters to some images.

Currently imagekit SourceGroup has not been implemented therefore the imagekit generateimages management command will not generate images for django-lazy-srcset. If you want to pre-generate images you can render_to_string() your templates in an appropriate save method or signal. If you are using django-content-blocks this happens on publish anyway.

Clean up of old, unused files created by django-lazy-srcset is down to you, if you require it at all.

Development Status & Roadmap

Django lazy srcset is in beta. There are currently no plans for further development.

Dependencies & Thank You

• https://github.com/matthewwithanm/django-imagekit/

Other Packages to Consider

• https://github.com/codingjoe/django-pictures