/client-hints

🕵️‍♂️ Parse client hints headers

Primary LanguageTypeScript

client-hints

🕵️‍♂️ Parse client hints headers and provide a convenient API to access device information and user preferences

Use client hints, where available

import { ClientHints } from "client-hints";
import { userAgentParser } from "some-user-agent-parser-library";

app.get("/api-endpoint", (req, res) => {
  const hints = new ClientHints(req);

  const isMobile =
    hints.mobile ?? // cheap
    userAgentParser(req.get("user-agent")).device?.type === "mobile"; // more expensive

  const browserName =
    hints.vendorName ?? // cheap
    userAgentParser(req.get("user-agent")).browser?.name; // more expensive

  console.log(JSON.stringify(hints, null, 2)); // Serialises all available hints

  res.send(`${isMobile ? "Mobile" : "Desktop"} browser: ${browserName}`);
});

Available detections

All detections return undefined if the relevant header is not available.

Feature Type Header Meaning Adoption level
arch, architecture string Sec-CH-UA-Arch CPU architecture Experimental
bitness number Sec-CH-UA-Bitness CPU bitness (32, 64) Experimental
contentDpr, contentDevicePixelRatio number Content-DPR Image device pixel ratio Deprecated
deviceMemory number Device-Memory Appr. available RAM Experimental
downlink number Downlink Network speed (Mbps) Experimental
dpr, devicePixelRatio number DPR Device pixel ratio Deprecated
ect, effectiveConnectionType string ECT Network profile (G) Experimental
fetchDest, fetchDestination string Sec-Fetch-Dest Resource type
fetchMode string Sec-Fetch-Mode Navigation type
fetchSite string Sec-Fetch-Site Relationship to origin
fetchUser boolean Sec-Fetch-User Was the request triggered by user action
gpc boolean Sec-GPC Consents to sell or share personal information Experimental
mobile boolean Sec-CH-UA-Mobile Boolean: Is this a mobile device Experimental
model string Sec-CH-UA-Model Device model Experimental
platform string Sec-CH-UA-Platform Operating system name Experimental
platformVersion string Sec-CH-UA-Platform-Version Operating system version Experimental
prefersColorScheme string Sec-CH-Prefers-Color-Scheme User's preferred color scheme Experimental
prefersReducedMotion boolean Sec-CH-Prefers-Reduced-Motion User prefers reduced motion Experimental
prefersReducedTransparency boolean Sec-CH-Prefers-Reduced-Transparency User prefers reduced transparency Experimental
purpose string Sec-Purpose Resource purpose (prefetch) Experimental
vendorName string Sec-CH-UA / Sec-CH-UA-Full-Version-List Browser Name Experimental
vendorVersion string Sec-CH-UA-Full-Version / Sec-CH-UA / Sec-CH-UA-Full-Version-List Browser version Experimental
viewportWidth number Viewport-Width Layout viewport width Deprecated
width number Width Resource desired width Deprecated

Client Hints Instructions Response Header

Set the value of Accept-CH header to include the headers you want the browse to send.

Accept-CH: Sec-CH-UA-Mobile,Sec-CH-UA-Full-Version,Sec-CH-UA-Full-Version-List,Sec-CH-UA-Model,Sec-CH-UA-Platform,Sec-CH-UA-Platform-Version,ECT

Include all available hints:

Accept-CH: *