README

Breakpoints is currently in beta. APIs, configuration, and generated transform-set structure may change before the stable 1.0.0 release.

Breakpoints handles the front end markup for your Craft assets and provides a developer processing tool to accurately measure each breakpoint rendering size and create transform sets without any manual work.

Processing is intended for local development environments with the resulting transform sets being commited to git.

Key concepts

• Transform set — a named, reusable recipe (e.g. hero, card) describing the image dimensions, format, and quality at each breakpoint. Stored as JSON in config/breakpoints/transform-sets.json.
• Breakpoint slots — every set has a base slot (smallest viewport) followed by one slot per configured breakpoint (xs, sm, md, …), in width order.
• Processing run — a control-panel pass that renders a chosen entry, measures the rendered size of each breakpoint image, and lets you apply those measurements back into the set.
• Escape width — an optional extra-large variant for the final slot, to keep very wide layouts sharp.
• DPR variants — high-density srcset descriptors (1x always; opt in to 2x/3x).

Features

• One <source> per configured breakpoint, with correct media ranges.
• Primary format plus an optional secondary <source> fallback (e.g. AVIF + WebP).
• DPR srcset density descriptors.
• SVG assets pass through to a plain <img> (no <picture>).
• Native loading="lazy" / decoding control.
• Fully overridable Twig templates for custom markup and lazy-loading integrations.
• File-backed transform sets that are commit-friendly and reviewable in version control.

Requirements

• PHP ^8.2
• Craft CMS ^5.3.0

Install

Option 1: Composer

Install with Composer:

composer require craftyhedge/breakpoints:^0.1.0

To pin the exact release:

composer require craftyhedge/breakpoints:0.1.0

Then install the plugin:

php craft plugin/install breakpoints

Option 2: Plugin Store (Control Panel)

1. Open the Craft Control Panel.
2. Go to Plugin Store.
3. Find Breakpoints.
4. Click Install.

Quick start

1. Render the image in a template:

   {{ image(entry.heroImage.one(), 'hero', {
     initWidth: 1200,
     initHeight: 675
   }) }}

2. Keep building the component with that usable output.

3. When the layout is ready, open Breakpoints → Transform Sets, process the entry to create the transform set. Review and edit as needed.

4. Put shared defaults, especially breakpoint widths, in config/breakpoints.php. Use Breakpoints → Settings for quick output/default changes.

See Getting Started for the full walkthrough.

Documentation

• Getting Started — render a usable image, finalize the set.
• Configuration — settings, the config file, and precedence.
• Responsive Images — the output model, media ranges, DPR, and escape width.
• Custom Image Templates — render through your own Twig.
• image() Twig Function — full API reference.
• Release history

Support

• Source: https://github.com/craftyhedge/breakpoints
• Issues: https://github.com/craftyhedge/breakpoints/issues

License

Commercial plugin licensing follows the Craft License model.

See LICENSE.md.