Skip to content
This repository was archived by the owner on Aug 3, 2023. It is now read-only.

Commit 5658f45

Browse files
jamespleasejamesplease
committed
Update docs
1 parent f398324 commit 5658f45

File tree

1 file changed

+71
-33
lines changed

1 file changed

+71
-33
lines changed

‎README.md

Lines changed: 71 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,9 @@ yarn add react-request
4949
- [Getting Started](#getting-started)
5050
- [API](#api)
5151
- [\<Fetch/\>](#fetch-)
52+
- [props](#props)
53+
- [Arguments passed to the render prop](#children)
54+
- [Using `doFetch`](#using-dofetch)
5255
- [fetchDedupe()](#fetchdedupe-input--init--dedupeoptions-)
5356
- [getRequestKey()](#getrequestkey-url-method-body-responsetype-)
5457
- [isRequestInFlight()](#isrequestinflight-requestkey-)
@@ -152,28 +155,51 @@ to learn more.
152155

153156
#### `<Fetch />`
154157

155-
A component for making a single HTTP request. It accepts every value of `init` and `input`
158+
A component for making a single HTTP request. This is the export from this library that you will use
159+
most frequently.
160+
161+
```jsx
162+
import { Fetch } from 'react-request';
163+
```
164+
165+
##### Props
166+
167+
The `<Fetch/>` components accepts every value of `init` and `input`
156168
from the
157169
[`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch)
158170
API as a prop, in addition to a few other things.
159171

160-
The props that come from the `fetch()` method are:
161-
162-
- `url`
163-
- `method`: defaults to `"GET"`
164-
- `body`
165-
- `credentials`
166-
- `headers`
167-
- `mode`
168-
- `cache`
169-
- `redirect`
170-
- `referrer`: defaults to `"about:client"`
171-
- `referrerPolicy`: defaults to `""`
172-
- `integrity`: defaults to `""`
173-
- `keepalive`
174-
- `signal`
175-
176-
To learn more about the valid options for these props, refer to the
172+
The complete list of props is:
173+
174+
| Prop | Default value | Description |
175+
| ------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
176+
| url | | From [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch). The URL to send the request to |
177+
| method | `'GET'` | From [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch). The HTTP method to use |
178+
| body | | From [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch). The request body to send along with the request |
179+
| credentials | | From [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch). The request credentials you want to use for the request: `omit`, `same-origin`, or `include.` |
180+
| headers | | From [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch). Headers to send along with the request |
181+
| [children](#children) | | A function that is called with a single argument containing information about the request. Learn more. |
182+
| [lazy](#lazy) | _Varies_ | Whether or not the request is made when the component mounts. |
183+
| [beforeFetch](#beforefetch) | | A function called before a network request is made. |
184+
| [afterFetch](#afterfetch) | | A function that is only called after a network request is made. |
185+
| [onResponse](#onresponse) | | A function called anytime a response is received, whether from the network or cache. |
186+
| [transformData](#transformdata) | | A function that is called with the body of the response, allowing you to transform it. |
187+
| [responseType](#responsetype) | `'json'` | Whether or not the request is made when the component mounts. |
188+
| [requestName](#requestname) | | A name to give this request, which can be useful for debugging. |
189+
| [fetchPolicy](#fetchpolicy) | | The cache strategy to use. |
190+
| [cacheResponse](#cacheresponse) | _Varies_ | Whether or not to cache the response for this request. |
191+
| [dedupe](#dedupe) | `true` | Whether or not to dedupe this request. |
192+
| [requestKey](#requestkey) | _Generated_ | A key that is used for deduplication and response caching. |
193+
| mode | | From [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch). The mode you want to use for the request |
194+
| cache | | From [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch). The browser's cache mode you want to use for the request |
195+
| redirect | | From [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch). The redirect mode to use |
196+
| referrer | `'about:client'` | From [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch). The referrer to use for the request |
197+
| referrerPolicy | `''` | From [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch). Specifies the value of the referer HTTP header. |
198+
| integrity | `''` | From [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch). Contains the [subresource integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) value of the request |
199+
| keepalive | | From [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch). Can be used to allow the request to outlive the page |
200+
| signal | | From [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch). An AbortSignal object instance |
201+
202+
To learn more about the valid options for the props that come from `fetch`, refer to the
177203
[`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch)
178204
documentation.
179205

@@ -201,21 +227,19 @@ In addition to the `fetch()` props, there are a number of other useful props.
201227
The [render prop](https://cdb.reacttraining.com/use-a-render-prop-50de598f11ce) of this component.
202228
It is called with one argument, `result`, an object with the following keys:
203229

204-
- `fetching`: A Boolean representing whether or not a request is currently in flight for this component
205-
- `failed`: A Boolean representing whether or not the request failed for any reason. This includes network
206-
errors and status codes that are greater than or equal to`400`.
207-
- `error`: An error object representing a network error occurred. Note that HTTP "error" status codes do not
208-
cause errors; only failed or aborted network requests do. For more, see the
209-
["Using Fetch" MDN guide](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#Checking_that_the_fetch_was_successful).
210-
- `response`: An instance of [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). The
211-
[`body`](https://developer.mozilla.org/en-US/docs/Web/API/Body) will already be read, and made
212-
available to you as `response.data`.
213-
- `data`: The data returned in `response`. This will be different from `response.data` if a
214-
`transformData` prop was passed to `<Fetch/>`.
215-
- `doFetch`: A function that makes the HTTP request. See notes below.
216-
- `url`: The URL that was passed into `<Fetch />`.
217-
- `requestName`: The name of the request (see `requestName` below)
218-
- `requestKey`: The computed [request key](./docs/guides/request-keys.md)
230+
| Key | Type | Description |
231+
| ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
232+
| fetching | Boolean | A Boolean representing whether or not a request is currently in flight for this component |
233+
| failed | Boolean | A Boolean representing whether or not the request failed for any reason. This includes network errors and status codes that are greater than or equal to`400`. |
234+
| error | Object | An error object representing a network error occurred. Note that HTTP "error" status codes do not cause errors; only failed or aborted network requests do. For more, see the ["Using Fetch" MDN guide](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#Checking_that_the_fetch_was_successful). |
235+
| response | Object | An instance of [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). The [`body`](https://developer.mozilla.org/en-US/docs/Web/API/Body) will already be read, and made available to you as `response.data`. |
236+
| data | Object | The data returned in `response`. This will be different from `response.data` if a `transformData` prop was passed to `<Fetch/>`. |
237+
| doFetch | Function | A function that allows you to manually make the HTTP request. [Read more.](#using-dofetch) |
238+
| url | String | The URL that was passed as a prop to `<Fetch />` |
239+
| requestName | String | The name of the request (see `requestName` below) |
240+
| requestKey | String | The [request key](./docs/guides/request-keys.md) of the request |
241+
242+
###### Using doFetch
219243

220244
There are three common use cases for the `doFetch` prop:
221245

@@ -232,6 +256,20 @@ component's state.
232256
`doFetch` returns a Promise that **always** resolves. It resolves to the same argument that the
233257
[`afterFetch`](#afterFetch) prop receives.
234258

259+
In the following example, we demonstrate how you can modify the request by passing options to `doFetch`.
260+
261+
```jsx
262+
<Fetch {...props}>
263+
{({ doFetch }) => (
264+
// You can pass options to `doFetch` to customize the request. All of the props from `fetch()`, such as `url`,
265+
// `body`, and so on, are supported.
266+
<button onClick={() => doFetch({ body: this.getResponseBody() })}>
267+
Perform Action
268+
</button>
269+
)}
270+
</Fetch>
271+
```
272+
235273
##### `lazy`
236274

237275
Whether or not the request will be called when the component mounts. The default value

0 commit comments

Comments
 (0)