Headers

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨March 2017⁩.

* Some parts of this feature may have varying levels of support.

Note: This feature is available inWeb Workers.

TheHeaders interface of theFetch API allows you to perform various actions onHTTP request and response headers. These actions include retrieving, setting, adding to, and removing headers from the list of the request's headers.

You can retrieve aHeaders object via theRequest.headers andResponse.headers properties, and create a newHeaders object using theHeaders() constructor. Compared to using plain objects, usingHeaders objects to send requests provides some additional input sanitization. For example, it normalizes header names to lowercase, strips leading and trailing whitespace from header values, and prevents certain headers from being set.

Note:You can find out more about the available headers by reading ourHTTP headers reference.

Description

AHeaders object has an associated header list, which is initially empty and consists of zero or more name and value pairs. You can add to this using methods likeappend() (seeExamples.) In all methods of this interface, header names are matched by case-insensitive byte sequence.

An object implementingHeaders can directly be used in afor...of structure, instead ofentries():for (const p of myHeaders) is equivalent tofor (const p of myHeaders.entries()).

Modification restrictions

SomeHeaders objects have restrictions on whether theset(),delete(), andappend() methods can mutate the header. The modification restrictions are set depending on how theHeaders object is created.

For headers created withHeaders() constructor, there are no modification restrictions.
For headers ofRequest objects:
- If the request'smode isno-cors, you can modify anyCORS-safelisted request header name/value.
- Otherwise, you can modify anynon-forbidden request header name/value.
For headers ofResponse objects:
- If the response is created usingResponse.error() orResponse.redirect(), or received from afetch() call, the headers are immutable and cannot be modified.
- Otherwise, if the response is created usingResponse() orResponse.json(), you can modify anynon-forbidden response header name/value.

All of the Headers methods will throw aTypeError if you try to pass in a reference to a name that isn't avalid HTTP Header name. The mutation operations will throw aTypeError if the header is immutable. In any other failure case they fail silently.

Constructor

Headers(): Creates a newHeaders object.

Instance methods

Headers.append(): Appends a new value onto an existing header inside aHeaders object, or adds the header if it does not already exist.
Headers.delete(): Deletes a header from aHeaders object.
Headers.entries(): Returns aniterator allowing to go through all key/value pairs contained in this object.
Headers.forEach(): Executes a provided function once for each key/value pair in thisHeaders object.
Headers.get(): Returns aString sequence of all the values of a header within aHeaders object with a given name.
Headers.getSetCookie(): Returns an array containing the values of allSet-Cookie headers associated with a response.
Headers.has(): Returns a boolean stating whether aHeaders object contains a certain header.
Headers.keys(): Returns aniterator allowing you to go through all keys of the key/value pairs contained in this object.
Headers.set(): Sets a new value for an existing header inside aHeaders object, or adds the header if it does not already exist.
Headers.values(): Returns aniterator allowing you to go through all values of the key/value pairs contained in this object.

Note:To be clear, the difference betweenHeaders.set() andHeaders.append() is that if the specified header does already exist and does accept multiple values,Headers.set() will overwrite the existing value with the new one, whereasHeaders.append() will append the new value onto the end of the set of values. See their dedicated pages for example code.

Note:When Header values are iterated over, they are automatically sorted in lexicographical order, and values from duplicate header names are combined.

Examples

In the following snippet, we create a new header using theHeaders() constructor, add a new header to it usingappend(), then return that header value usingget():

const myHeaders = new Headers();myHeaders.append("Content-Type", "text/xml");myHeaders.get("Content-Type"); // should return 'text/xml'

The same can be achieved by passing an array of arrays or an object literal to the constructor:

let myHeaders = new Headers({  "Content-Type": "text/xml",});// or, using an array of arrays:myHeaders = new Headers([["Content-Type", "text/xml"]]);myHeaders.get("Content-Type"); // should return 'text/xml'