What Are Client Hints and Are They Worth Implementing

By Cody Arsenault
Updated on October 7, 2022
What Are Client Hints and Are They Worth Implementing

The concept of responsive web design has been around for a while, but all of the kinks have yet to be ironed out. The exponential proliferation of connected devices with varying software and technical capabilities has made it more and more difficult to cater web content to every single user.

Furthermore, trying to accommodate everyone often leads to cluttered markup that negatively impacts performance. Client hints were created to streamline the process of resource selection so that developers can build better responsive web apps more efficiently.

What are client hints?

Client hints were introduced by Google for Chrome, and other browsers have adopted them since the HTTP specification was released. Client hints allow for proactive content negotiation by letting user agents determine how images and other resources get displayed on individual devices. They act as a sort of liaison between the client and the server to put together the best page layout possible.

Why use client hints?

One of the biggest challenges of responsive web design is creating clean markup.

For example, making images responsive can require you to specify multiple image breakpoints and pixel densities. If you're not careful, you could end up with some sloppy, bloated code.

Implementing hints saves time for both you and your users by drastically reducing the amount of code needed to make your page elements responsive. They essentially automate the resources selection process. For instance, if you want to offer multiple versions of an image, adding hints to the HTTP request helps the web server automatically pick which one is the best fit for the user's device. Decoupling your markup from your images also allows you to alter images without it affecting your markup.

Automating resource selection with client hints doesn't just save you time and energy. The true benefit is improved performance, which means a better user experience. According to tests conducted by Smashing Magazine, making your images responsive with hints requires 19-32 percent less data to be served than using preselected image breakpoints. Consequently, the server will send better quality images at a faster rate.

Client hints aren't just for images. They are helpful wherever you have breakpoints based on viewport size or DPR in your CSS. See the Google Dev Guide's section on client hints to learn more about their uses.

How do client hints work?

All requests that a browser sends to a server includes HTTP request headers. Client hints take the form of HTTP request header fields. Adding them instructs the server to look at certain parameters on users' devices when deciding how to deliver content. The following shows an example of the request and response headers from the client and server when client hints are used.

Source: Google

In the example above, the client is basically telling the server to retrieve /image/thing. It also specifies that it accepts WebP format and provides client hints for the image's DPR, viewport width, and the intended display width. This information is then processed by the server which returns an image with the requested client hint specifications. In this case, the server used the DPR and Width hints as can be seen within the Vary response header.

Commonly used client hint headers include:

  • DPR, or "device pixel ratio," which means the ratio of physical screen pixels to CSS pixels.
  • Viewport-Width, which is quantified in CSS pixels.
  • Width, or the width of an image in physical pixels.
  • Downlink, which represents the user's maximum download speed.

There are a few others, but not all are available in every browser. The list of available hints will certainly grow as more browsers start supporting them.

Client hints browser support

Client hints work wonders for Chrome, Edge and Opera users, but they can potentially create problems for visitors who have unsupported browsers. Hopefully, this drawback will not be an issue in the future; however, in the meantime, developers might want to consider combining hints with relative widths and heights to prevent layout breaks. Using an image optimization service may help mitigate the risks of serving excessively large images to unsupported browsers.

How to enable client hints

Before you can start including hints, you must prepare the server to accept them. Since enabling client hints adds a little bit to your payload, there is no need to turn them on if you don't need them. To enable hints, insert the following header to your server's config file:

Accept-CH: DPR, Width, Viewport-Width

If adding the header is not an option, you can add the following meta tag under the head element of your markup instead:

<meta http-equiv="Accept-CH" content="DPR,Width,Viewport-Width">

You must individually list each hint that you want the server to accept. Therefore, if you wish to enable the downlink hint, you must add "Downlink" to the above snippet. The user's browser should now append the specified headers to all future server requests. If you're viewing your website in Chrome, use the "Network" panel to see the headers being sent.

Using hints to deliver responsive images

Although client hints have other uses, they are typically employed to deliver responsive web images. Responsive images adapt to the user's browser and screen. If you want to make an image responsive using hints, then there are a couple of steps that you need to take:

  1. Opt into client hints by including the HTTP header or meta tag in the head element of your markup.
  2. Be sure to set the Sizes attribute for all of your image tags.

As of now, the client hints specification requires the sizes attribute be set for the Width header to work properly. As mentioned earlier, the sizes attribute defines the layout and the display size of an image.

The traditional way to serve multiple versions of an image is to use the srcset attribute like so:

<img srcset="image-160.jpg 160w,
             image-320.jpg 320w,
             image-640.jpg 640w,
             image-1280.jpg 1280w"
     sizes="(max-width: 480px) 100vw,
            (max-width: 900px) 33vw,
     src="image.jpg" alt="image">

The srcset attribute allows the browser to choose from different image sizes. This method works fine, but that's a lot of code for one image.

Client hints eliminate the need for srcset. The Width attribute, for example, uses the value of the sizes attribute to calculate the exact width of the image on the page. With hints enabled, the browser sends a request like this to the server:

GET image.jpg
Accept: image/webp,image/*,*/*;q=0.8
DPR: 2
Viewport-Width: 1024
Width: 508

In this example, the browser tells the server that the requesting device has a pixel ratio of 2 and a viewport width of 1024. With that information, the server will return an image that is twice the size of the original to perfectly fit in the user's browser. Now, if you have hints enabled, the previous example can be reduced to the following:

<img sizes="(max-width: 480px) 100vw,
            (max-width: 900px) 33vw,
     src="image.jpg" alt="image">

As you can see, taking advantage of hints can cut down on the amount of code needed to ensure your website is responsive.

Client hints and the Accept header

If you're well versed on the topic of responsive web design, then you may be familiar with the Accept header. Client hints can be combined with the Accept header to serve the same image in various formats.

The Accept header works similarly to the other client hint headers. It tells the server which media types are acceptable to the browser. For example, whenever Chrome requests an image, it automatically includes an Accept header in the HTTP requests like so:

Accept: image/webp,image/*,*/*;q=0.8

This snippet lets the server know that Chrome prefers the WebP image format; however, if WebP isn't an option, then it should serve a file with a mime type beginning with image/\*. If that isn't available, then \*/* indicates that the server should serve whatever it has. Finally, the q=0.8 part indicates how strongly the browser prefers the specified format. The Mozilla Developer's Guide has more information about the Accept header specification and the quality preference parameter.

Enabling the Accept header allows you to further simplify your markup if you want to support multiple image formats. Chrome automatically includes the aforementioned Accept header, but other browsers do not have built-in preferences. Therefore, you must add your own Accept header in the head element of your markup to enable it for all users. Feel free to copy the Chrome default example, or use it as a guide to set your own preferences.

Client hints and the Vary header

The Vary header also plays an important role in the processing of client hints when using a web proxy. Essentially, the Vary header ensures that the right content is delivered to the right browser. For example, if an older browser which doesn't support Gzip compression and a newer browser which does support Gzip compression both make a request for an asset, the Vary header is instrumental in determining which version of the asset gets delivered to which browser.

According to IETF, in the event that more than one client hint is provided and if the asset is cacheable, the server is required to generate a Vary header. This helps in determining which hints can affect the response and if the response is suitable for a later request.

Security considerations

Although very helpful for the delivery of responsive images, client hints can impose some security concerns that implementers should be aware of. Since client hints do provide granular information about the browser (e.g. viewport width) this can help identify the user across multiple requests. What's more, if a user makes a request to domain.com, the client hints are not only sent to that domain but also to all of its subdomains and third parties.

If a third party website with negative intentions has access to client hints they may be able to identify some users through a combination of the client hint data they collect and your IP address for example. With these pieces of information they could then potentially track you as you move across the web.

According to the HTTP Working Group, there are however a few things that can be done to help reduce privacy concerns:

  • Implementers SHOULD restrict delivery of some or all client hints header fields to the opt-in origin only.
  • Implementers MAY provide user choice mechanisms so that users may balance privacy concerns with bandwidth limitations.
  • Implementations specific to certain use cases or threat models MAY avoid transmitting some or all of Client Hints header fields.


Setting up client hints takes a little time and effort, but it can pay off. You'll have responsive image tags that are much more manageable, and your users will always receive content that is optimized for their device in as few bytes as possible.

However, for now, browser support is still fairly limited. This makes it difficult to implement globally in the case of a CDN such as KeyCDN as this would require a change on the origin server's side. Although KeyCDN doesn't currently support client hints, this could change in the future based on how the adoption rate continues.

  • Share

Supercharge your content delivery 🚀

Try KeyCDN with a free 14 day trial, no credit card required.

Get started


Comment policy: Comments are welcomed and encouraged. However, all comments are manually moderated and those deemed to be spam or solely promotional in nature will be deleted.
  • **bold**
  • `code`
  • ```block```
KeyCDN uses cookies to make its website easier to use. Learn more