Skip to content

Client Hints

Peakhour uses client hints to provide optimised images based on the capabilities of the client's device. Client hints are additional headers that the browser sends to the server that request information about the client's runtime environment. By taking into account these hints, Peakhour can ensure that it provides the best possible images based on the client's device capabilities.

Supported Client Hints

Peakhour currently supports the following client hints when transforming images:

  • DPR (Device Pixel Ratio)
  • Width
  • Save-Data

When the width or DPR hints are present, the optimiser now derives a set of breakpoints that match the incoming device characteristics. Those derived values are threaded through the entire transformation pipeline as cloned API parameters, ensuring that downstream filters (resizing, encoding, watermarking, etc.) all work with the negotiated dimensions.

Implementing Client Hints

Client hints can be implemented in two ways:

  1. By using a meta tag in the section of the HTML document:
<meta http-equiv="Accept-CH" content="DPR, Width, Viewport-Width">
  1. By including the Accept-CH header in the server's response:
Accept-CH: DPR,Width,Device-Memory,Content-DPR,Downlink,ECT,Save-Data,Viewport-Width,rtt

Sizes Attribute and Media Conditions

In order to ensure that images are displayed correctly, the sizes attribute can be added to the tag to specify the size of the image based on a set of media conditions.

For example:

<img sizes="100vw" src="/images/sample.jpg"/>

The 100vw value in the sizes attribute tells the browser to assume that the image should fill the entire width of the browser window.

Media conditions, which are part of a media query, allow developers to specify conditions for different devices or viewport sizes. The following types of media conditions can be used:

  1. Plain condition: (min-width: 900px)
  2. Not condition: not (orientation: landscape)
  3. And condition: (orientation: landscape) and (min-width: 900px)
  4. Or condition: (orientation: portrait) or (max-width: 500px)

Automating with Lazysizes

Lazysizes is a popular library that can be used to automatically calculate the sizes attribute for responsive images. The library can be found on GitHub at https://github.com/aFarkas/lazysizes.

<img data-src="image.jpg" data-sizes="auto" class="lazyload" />

By including the data-sizes="auto" attribute, Lazysizes will automatically calculate the correct sizes attribute based on the client's device capabilities.

How Peakhour Responds to Client Hints

Once the optimiser has derived suitable width and DPR values, it exposes the available combinations in the response headers:

  • Variants-06 lists the negotiated width breakpoints (width=(...)) and DPR values (dpr=(...)), as well as the content-types that will be served.
  • Variant-Key-06 reflects the specific width/DPR/content-type that was used for the current response.
  • Vary is automatically extended with Width and/or DPR so CDN layers and browsers cache each variant separately.

If no additional breakpoints are required (for example, the source image is already smaller than the requested width), the optimiser retains the legacy header format and continues to serve the original asset.

Preset and Override Order

You can chain multiple named transforms with repeated t parameters (or comma-separated names). Presets are applied in order, header overrides from peakhour-optimiser-options are merged next, and finally explicit query parameters win. This precedence matches how the runtime filters propagate their cloned options and guarantees that manual overrides remain intact even when automatic width/DPR adjustments are introduced.