Headers
=======

The **`Headers`** interface of the Fetch API allows you to perform various actions on HTTP request and response headers. These actions include retrieving, setting, adding to, and removing headers from the list of the request's headers.

A `Headers` 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 like `append()` (see Examples.) In all methods of this interface, header names are matched by case-insensitive byte sequence.

For security reasons, some headers can only be controlled by the user agent. These headers include the forbidden header names and forbidden response header names.

A Headers object also has an associated guard, which takes a value of `immutable`, `request`, `request-no-cors`, `response`, or `none`. This affects whether the `set()`, `delete()`, and `append()` methods will mutate the header. For more information see Guard.

You can retrieve a `Headers` object via the `Request.headers` and `Response.headers` properties, and create a new `Headers` object using the `Headers()` constructor.

An object implementing `Headers` can directly be used in a `for...of` structure, instead of `entries()`: `for (const p of myHeaders)` is equivalent to `for (const p of myHeaders.entries())`.

**Note:** you can find out more about the available headers by reading our HTTP headers reference.

**Note:** This feature is available in Web Workers

Constructor
-----------

`Headers()`

Creates a new `Headers` object.

Instance methods
----------------

`Headers.append()`

Appends a new value onto an existing header inside a `Headers` object, or adds the header if it does not already exist.

`Headers.delete()`

Deletes a header from a `Headers` object.

`Headers.entries()`

Returns an `iterator` 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 this `Headers` object.

`Headers.get()`

Returns a `String` sequence of all the values of a header within a `Headers` object with a given name.

`Headers.getSetCookie()`

Returns an array containing the values of all `Set-Cookie` headers associated with a response.

`Headers.has()`

Returns a boolean stating whether a `Headers` object contains a certain header.

`Headers.keys()`

Returns an `iterator` 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 a `Headers` object, or adds the header if it does not already exist.

`Headers.values()`

Returns an `iterator` allowing you to go through all values of the key/value pairs contained in this object.


**Note:** To be clear, the difference between `Headers.set()` and `Headers.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, whereas `Headers.append()` will append the new value onto the end of the set of values. See their dedicated pages for example code.

**Note:** All of the Headers methods will throw a `TypeError` if you try to pass in a reference to a name that isn't a valid HTTP Header name. The mutation operations will throw a `TypeError` if the header has an immutable Guard. In any other failure case they fail silently.

**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 the `Headers()` constructor, add a new header to it using `append()`, then return that header value using `get()`:


```js
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:


```js
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'
```

Specifications
--------------

| Specification |
| --- |
| Fetch Standard # headers-class |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* ServiceWorker API
* HTTP access control (CORS)
* HTTP