Client Hints (ch)¶

Client Hints allow the image optimisation API to automatically respond to browser-provided information about the viewport, device pixel ratio, and network conditions to deliver optimally sized and formatted images.

Parameters¶

Parameter	Type	Description
`width`	boolean	Enable viewport width client hint support
`dpr`	boolean	Enable device pixel ratio client hint support
`savedata`	boolean	Enable save-data client hint support for data-conscious users

Usage¶

Enable client hints by setting the desired parameters to true:

?ch=width,dpr,savedata

Or enable individual hints:

?width=true&dpr=true&savedata=true

Examples¶

Enable all client hints¶

https://your-domain.com/image.jpg?ch=width,dpr,savedata

Enable viewport width and DPR hints only¶

https://your-domain.com/image.jpg?ch=width,dpr

Enable save-data hint for bandwidth optimization¶

https://your-domain.com/image.jpg?ch=savedata

Client Hint Types¶

Width (`width`)¶

When enabled, the API will use the browser's viewport width client hint to determine the optimal image width. The optimiser will calculate a series of width breakpoints (stops) and carry the chosen value through every filter as a cloned set of API options.

Device Pixel Ratio (`dpr`)¶

When enabled, the API will use the device pixel ratio client hint to serve appropriately scaled images for high-DPI displays. The negotiated DPR is preserved alongside the negotiated width so that downstream resizing and encoding use the correct pixel budget.

Save Data (`savedata`)¶

When enabled, the API will detect the save-data client hint and deliver more compressed images to users who have enabled data saving mode in their browser.

Response Headers¶

When either width or DPR hints are active, responses include additional metadata describing the negotiated variants:

Variants-06: Lists width breakpoints and DPR values (for example, width=(1024 768 512), dpr=(1 2)), followed by the content-types that will be served.
Variant-Key-06: Identifies the specific width/DPR/content-type tuple used for the current response (for example, (768 2x image/webp)).
Vary: Automatically includes Width and/or DPR so that downstream caches maintain separate entries per variant.

If no breakpoints are required (e.g. the source asset is smaller than the requested width), the optimiser retains the existing header format and continues to emit just the negotiated content-types.

Preset Order and Overrides¶

The optimiser now supports multiple t parameters (or comma-separated preset names). Presets are applied in the order they are provided, later presets overriding earlier ones. Header overrides from peakhour-optimiser-options are merged next, and explicit query parameters win last. This precedence guarantees that manual overrides remain intact even when automatic width/DPR cloning is used to drive the pipeline.

Browser Support¶

Client Hints are supported by modern browsers. The API gracefully degrades when client hints are not available.