fetch() global function
=======================

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

The global **`fetch()`** method starts the process of fetching a resource from the network, returning a promise that is fulfilled once the response is available.

The promise resolves to the `Response` object representing the response to your request.

 A `fetch()` promise only rejects when a network error is encountered (which is usually when there's a permissions issue or similar).
 A `fetch()` promise *does not* reject on HTTP errors (`404`, etc.).
 Instead, a `then()` handler must check the `Response.ok` and/or `Response.status` properties.

The `fetch()` method is controlled by the `connect-src` directive of Content Security Policy rather than the directive of the resources it's retrieving.

**Note:** The `fetch()` method's parameters are identical to those of the `Request()` constructor.

Syntax
------


```js
fetch(resource)
fetch(resource, options)
```

### Parameters

`resource`

This defines the resource that you wish to fetch. This can either be:

* A string or any other object with a stringifier — including a `URL` object — that provides the URL of the resource you want to fetch.
* A `Request` object.

`options` Optional

 An object containing any custom settings you want to apply to the request.
 The possible options are:


`method`

 The request method, e.g., `"GET"`, `"POST"`.
 The default is `"GET"`.
 Note that the `Origin` header is not set on Fetch requests with a method of `HEAD` or `GET`.
 Any string that is a case-insensitive match for one of the methods in RFC 9110 will be uppercased automatically.
 If you want to use a custom method (like `PATCH`), you should uppercase it yourself.


`headers`

 Any headers you want to add to your request, contained within a `Headers` object or an object literal with `String` values.
 Note that some names are forbidden.


**Note:** The `Authorization` HTTP header may be added to a request, but will be removed if the request is redirected cross-origin.

`body`

 Any body that you want to add to your request:
 this can be a `Blob`, an `ArrayBuffer`, a `TypedArray`, a `DataView`,
 a `FormData`, a `URLSearchParams`, string object or literal,
 or a `ReadableStream` object. This latest possibility is still experimental; check the compatibility information to verify you can use it.
 Note that a request using the `GET` or `HEAD` method cannot have a body.


`mode`

 The mode you want to use for the request, e.g., `cors`,
 `no-cors`, or `same-origin`.


`credentials`

Controls what browsers do with credentials (cookies, HTTP authentication entries, and TLS client certificates). Must be one of the following strings:

`omit`

Tells browsers to exclude credentials from the request, and ignore any credentials sent back in the response (e.g., any `Set-Cookie` header).

`same-origin`

Tells browsers to include credentials with requests to same-origin URLs, and use any credentials sent back in responses from same-origin URLs. **This is the default value.**

`include`

Tells browsers to include credentials in both same- and cross-origin requests, and always use any credentials sent back in responses.

**Note:** Credentials may be included in simple and "final" cross-origin requests, but should not be included in CORS preflight requests.



`cache`

A string indicating how the request will interact with the browser's HTTP cache. The possible values, `default`, `no-store`, `reload`, `no-cache`, `force-cache`, and `only-if-cached`, are documented in the article for the `cache` property of the `Request` object.

`redirect`

How to handle a `redirect` response:

`follow`

Automatically follow redirects. Unless otherwise stated the redirect mode is set to `follow`.

`error`

Abort with an error if a redirect occurs.

`manual`

 Caller intends to process the response in another context.
 See WHATWG fetch standard for more information.



`referrer`

 A string specifying the referrer of the request. This can be a
 same-origin URL, `about:client`, or an empty string.


`referrerPolicy`

 Specifies the referrer policy to use for the request. May be one of `no-referrer`,
 `no-referrer-when-downgrade`, `same-origin`,
 `origin`, `strict-origin`,
 `origin-when-cross-origin`,
 `strict-origin-when-cross-origin`, or `unsafe-url`.


`integrity`

 Contains the subresource integrity
 value of the request (e.g., `sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=`).


`keepalive`

 The `keepalive` option can be used to allow the request to outlive the page.
 Fetch with the `keepalive` flag is a replacement for the `Navigator.sendBeacon()` API.


`signal`

 An `AbortSignal` object instance; allows you to communicate with a
 fetch request and abort it if desired via an `AbortController`.


`priority`

Specifies the priority of the fetch request relative to other requests of the same type. Must be one of the following strings:

`high`

A high-priority fetch request relative to other requests of the same type.

`low`

A low-priority fetch request relative to other requests of the same type.

`auto`

Automatically determine the priority of the fetch request relative to other requests of the same type (default).


### Return value

A `Promise` that resolves to a `Response` object.

### Exceptions

`AbortError` `DOMException`

 The request was aborted due to a call to the `AbortController`
`abort()` method.


`TypeError`

Can occur for the following reasons:



| Reason | Failing examples |
| --- | --- |
| Invalid header name. | 
```
// space in "C ontent-Type"
const headers = {
  'C ontent-Type': 'text/xml',
  'Breaking-Bad': '<3',
};
fetch('https://example.com/', { headers });
        
```
 |
| Invalid header value. The header object must contain exactly two elements. | 
```
const headers = [
  ['Content-Type', 'text/html', 'extra'],
  ['Accept'],
];
fetch('https://example.com/', { headers });
        
```
 |
| Invalid URL or scheme, or using a scheme that fetch does not support, or using a scheme that is not supported for a particular request mode. | 
```
fetch('blob://example.com/', { mode: 'cors' });
        
```
 |
| URL includes credentials. | 
```
fetch('https://user:password@example.com/');
        
```
 |
| Invalid referrer URL. | 
```
fetch('https://example.com/', { referrer: './abc\u0000df' });
        
```
 |
| Invalid modes (`navigate` and `websocket`). | 
```
fetch('https://example.com/', { mode: 'navigate' });
        
```
 |
| If the request cache mode is "only-if-cached" and the request mode is other than "same-origin". | 
```
fetch('https://example.com/', {
  cache: 'only-if-cached',
  mode: 'no-cors',
});
        
```
 |
| 
 If the request method is an invalid name token or one of the forbidden headers
 (`'CONNECT'`, `'TRACE'` or `'TRACK'`).
  | 
```
fetch('https://example.com/', { method: 'CONNECT' });
        
```
 |
| 
 If the request mode is "no-cors" and the request method is not a CORS-safe-listed method
 (`'GET'`, `'HEAD'`, or `'POST'`).
  | 
```
fetch('https://example.com/', {
  method: 'CONNECT',
  mode: 'no-cors',
});
        
```
 |
| If the request method is `'GET'` or `'HEAD'` and the body is non-null or not undefined. | 
```
fetch('https://example.com/', {
  method: 'GET',
  body: new FormData(),
});
        
```
 |
| If fetch throws a network error. |  |

Examples
--------

 In our Fetch Request example (see Fetch Request live) we
 create a new `Request` object using the relevant constructor, then fetch it
 using a `fetch()` call. Since we are fetching an image, we run
 `Response.blob()` on the response to give it the proper MIME type so it will be
 handled properly, then create an Object URL of it and display it in an
 `<img>` element.


```js
const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    return response.blob();
  })
  .then((response) => {
    myImage.src = URL.createObjectURL(response);
  });
```


 In the Fetch with init then Request example (see Fetch Request init live), we do the same thing except that we pass in an
 `init` object when we invoke `fetch()`:


```js
const myImage = document.querySelector("img");

const myHeaders = new Headers();
myHeaders.append("Accept", "image/jpeg");

const myInit = {
  method: "GET",
  headers: myHeaders,
  mode: "cors",
  cache: "default",
};

const myRequest = new Request("flowers.jpg");

fetch(myRequest, myInit).then((response) => {
  // …
});
```


 You could also pass the `init` object in with the
 `Request` constructor to get the same effect:


```js
const myRequest = new Request("flowers.jpg", myInit);
```


 You can also use an object literal as `headers` in
 `init`.


```js
const myInit = {
  method: "GET",
  headers: {
    Accept: "image/jpeg",
  },
  mode: "cors",
  cache: "default",
};

const myRequest = new Request("flowers.jpg", myInit);
```

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

| Specification |
| --- |
| Fetch Standard # fetch-method |

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

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

See also
--------

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