Using Client Hints for Network-Aware Loading

1. What Client Hints are and how they work

Client Hints are a family of HTTP headers through which the browser proactively tells the server structured information about the user's device, preferences, and network conditions. Unlike the classic User-Agent string, a single hard-to-parse text field packed with redundant information, Client Hints deliver targeted, individually retrievable values such as screen width, preferred color scheme, or, relevant here, network quality.

For web performance, the so-called Network Information Client Hints matter most, which include Save-Data, Downlink, and ECT (Effective Connection Type). These headers let a server recognize, already on the first request, whether a user is on a slow mobile connection or has explicitly asked for reduced data usage, and adjust the response accordingly before a single byte of image data has even been transferred.

2. Opting in through the Accept-CH header

For privacy reasons, most Client Hints are not sent automatically with every request; the server must explicitly request them. This happens through the Accept-CH header, which the server sets in its response to tell the browser which Client Hints it should send on future requests to this origin. Only after this opt-in does the browser include the requested headers on subsequent requests.

This two-step logic means the very first page load still has to do without the desired hints, while every subsequent request within the same origin includes them automatically. For single-page applications or pages that load several additional resources, this is usually not an issue, since even the second request already benefits from the optimization.

# Server response to the first request: requesting Client Hints
HTTP/1.1 200 OK
Accept-CH: Save-Data, Downlink, ECT, DPR, Viewport-Width
Critical-CH: Save-Data

# The browser's subsequent request automatically includes:
GET /products/camera-xz200 HTTP/1.1
Save-Data: on
Downlink: 0.7
ECT: 3g
DPR: 2
Viewport-Width: 390

3. The Save-Data hint for explicit data frugality

The Save-Data header is the most important and easiest to use Client Hint, because it doesn't rely on a network measurement but on an explicit user decision. When a user turns on data saver mode in their operating system or browser settings, the browser sends the header Save-Data: on with every request, regardless of how fast the current connection actually is.

For the server, this hint is a clear signal: the user deliberately wants less data transferred, perhaps because of a limited data plan or because they're in a country with expensive mobile rates. Sensible responses include serving smaller image variants, disabling autoplay videos, or dropping non-essential web fonts and animations to noticeably reduce the amount of data transferred.

4. Downlink and ECT: estimating network quality

While Save-Data reflects a deliberate user decision, Downlink and ECT provide an automatic estimate of actual network quality. Downlink reports the estimated bandwidth as a floating-point number of megabits per second, while ECT (Effective Connection Type) provides a rough categorization into slow-2g, 2g, 3g, or 4g, based on measured round-trip time and throughput of the most recent requests.

These values are deliberately meant to be understood as an estimate rather than an exact measurement, since they're based on historical data from the same browser's recent requests, and actual connection quality can change at any moment, for example when switching from Wi-Fi to mobile data. Even so, they provide a valuable rough signal that is entirely sufficient for binary decisions such as 'serve the simple or the elaborate image variant'.

5. Adaptive delivery of image quality and content

The most practically important use case for Client Hints is adaptive image delivery. If the server detects a slow connection through Save-Data or a low ECT value, it can serve a more heavily compressed, lower-resolution image variant server-side, instead of leaving the decision entirely to the client via srcset. This reduces the transferred data volume already at the server level, without requiring additional client-side logic.

Beyond images, other content can be adapted too: video previews can be replaced with static thumbnails, the number of simultaneously loaded product recommendations can be reduced, or elaborate web font variants can be swapped for system fonts. It's important to design these adjustments so they never compromise the page's core functionality or readability, only optimize data volume and load time.

6. Practical implementation in the backend

In backend logic, Client Hints headers can be read like any other HTTP header and translated into a simple context object in one central place, such as a middleware or event listener. That object can then be queried in templates or image-rendering services to decide which image variant to serve or which content to reduce, without every single place in the code having to parse the headers itself.

It matters to set the Accept-CH header consistently across all pages of the application, since otherwise it won't reliably affect subsequent requests. The Vary header should also be set accordingly, so caching layers like CDNs correctly keep separate responses for different Client Hints values, instead of accidentally serving a response optimized for slow connections to a user with a fast one.

7. The client-side alternative: the NetworkInformation API

Besides the server-evaluated headers, the NetworkInformation API also offers client-side access to the same information, reachable through navigator.connection. This API exposes the same values as Downlink, ECT, and Save-Data directly in JavaScript, without needing a server round trip, which suits client-side decisions well, such as whether to autoplay a video or prefetch an image gallery.

Both approaches aren't mutually exclusive, they complement each other: the headers suit decisions that must already be settled by the first byte of the response, such as which image variant to serve, while the JavaScript API suits later, interactive decisions that only become relevant after the page has initially loaded.

8. Privacy considerations for Client Hints

Client Hints were deliberately designed to be less suited to fingerprinting than the User-Agent string, since they must be requested individually, and many of the more sensitive hints, such as detailed device information, are only transmitted after an explicit server opt-in and sometimes only over HTTPS. The Network Information hints such as Save-Data, Downlink, and ECT are considered comparatively low-risk, since they barely contribute to uniquely identifying an individual user.

Still, when processing this data, applicable data protection regulations should be observed, especially if network data is stored or evaluated together with other personal data. For purely real-time adjustment of delivery, without persistent storage of the values, no additional data protection requirements typically arise beyond those already in effect.

9. Browser support and the limits of the approach

Client Hints, and the Network Information hints in particular, are currently supported mainly by Chromium-based browsers such as Chrome and Edge, while Safari and Firefox have not implemented these headers so far. That means an optimization based on Client Hints simply has no effect for a substantial share of users, which should be factored into how this measure is prioritized.

For that reason, Client Hints should never serve as the sole basis of an optimization strategy, but should always be treated as an additional, progressive enhancement alongside fundamental techniques like responsive images with srcset and sizes. For browsers without support, those fundamental mechanisms keep working reliably, while users on supported browsers benefit from the additional, fine-grained adjustment.

10. Summary

11. FAQ: Client Hints