https://github.com/techniq/react-fetch-component
React component and hook to declaratively fetch data
https://github.com/techniq/react-fetch-component
fetch react
Last synced: about 1 year ago
JSON representation
React component and hook to declaratively fetch data
- Host: GitHub
- URL: https://github.com/techniq/react-fetch-component
- Owner: techniq
- License: mit
- Created: 2017-02-05T19:01:17.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2022-12-08T07:32:52.000Z (over 3 years ago)
- Last Synced: 2025-03-29T22:09:06.086Z (about 1 year ago)
- Topics: fetch, react
- Language: JavaScript
- Homepage:
- Size: 748 KB
- Stars: 158
- Watchers: 3
- Forks: 21
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# react-fetch-component [](https://circleci.com/gh/techniq/react-fetch-component)
React component to declaratively [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) data
## Install
```
yarn add react-fetch-component
```
or
```
npm install --save react-fetch-component
```
## Usage
You supply a single function as a child of `` which receives a single argument as an object. The function will be called anytime the state of the fetch request changes (for example, before a request has been made, while the request is in flight, and after the request returned a response).
While you can pass a single property to the function (for example, `(fetchProps) => ...`), it is common to instead use object destructuring to peel off the properties on the object you plan to use.
An example of destructing and using the most common properties `loading`, `error`, and `data`.
```js
{({ loading, error, data }) => (
{loading &&
{
/* handle loading here */
}}
{error &&
{
/* handle error here */
}}
{data &&
{
/* handle data here */
}}
)}
```
You can also use React's context via `` for accessing the state in a deep tree (or to create components based on state)
```js
const Loading = () => {({ loading }) => loading ? : null}
const Error = () => {({ error }) => error ? : null}
{({ data }) => { data ? /* handle data here */ : null}}
```
## Props
- `url` (string) - address of the request. Initial fetch will only be created when it's a non-empty string. You can initially set this to `undefined`, `false`, or an empty string to delay the fetch to a later render.
- `options` (object|function) - request options such as `method`, `headers`, `credentials`, etc. If passed as a function, it will not be evaluated until the request is sent, which is useful when calling expensive methods like `JSON.stringify` for `options.body` for example.
- see [Request properties](https://developer.mozilla.org/en-US/docs/Web/API/Request#Properties) for all available options.
- `as` - declare how to handle the response body
- default: `auto` (will attempt to parse body based on `Content-Type` header)
- can either be a string for any of the [body methods](https://developer.mozilla.org/en-US/docs/Web/API/Body#Methods) including:
- `arrayBuffer`
- `blob`
- `formData`
- `json`
- `text`
- or a `function` that takes in the `response` and returns a `Promise`. For example ` res.text()} />`
- or an `object` that maps the `Content-Type` of the response to a function that takes in the `response` and returns a `Promise`. For example ` JSON.parse(res.text(), customReviver)}} />`. `html`, `json`, `xml`, and `other` are also available for simplification.
- `cache` (boolean|object)
- If set, will cache responses by `url` and return values from cache for matches urls without issues another request. Useful for typeahead features, etc.
- If `true`, will use an instance of `SimpleCache` per component instance
- Can supply an instance with `get(url)` and `set(url, promise)` methods. Passing an instance of `SimpleCache` allows for multiple instances to share the same (simple) cache
- Other implementations of a cache can be supplied for more control (LRU, persist to local/sessionStorage, etc)
- default: `false`
- `manual` (boolean) - If `true`, requires calling `fetch` explicitly to initiate requests. Useful for better control of POST/PUT/PATCH requests.
- default: `false`
- `onDataChange` (function) - Function called only when data is changed. It is called before `onChange`, and if a result is returned (i.e. not `undefined`), this value will be used as `data` passed to `onChange` and the child function instead of the original data. `onDataChange` also receives the current data as the second parameter, which allows for concatenating data (ex. infinity scroll).
- `onChange` (function) - Function called with same props as child function. Useful to call `setState` (or dispatch a redux action) since this is not allowed within `render`. `onChange` will always be called even if `` component has been unmounted.
- default: `undefined`
- `fetchFunction` (function) - Specify own fetch function. Useful to debounce fetch requests (although probably best to debounce outside of `` so not call unneccessary renders)
- default: `window.fetch`
## Object properties passed to child function
- `loading`
- Set to `true` while request is in flight
- Set to `false` once response has returned
- Set to `null` when `manual={true}` before `fetch()` is called
- `error`
- Is `undefined` while request is pending
- Will be set to the parsed response body (`json` by default) if `!response.ok` (i.e. status < 200 || status >= 300)
- Will be set to an `Error` instance if thrown during the request (ex. CORS issue) or if thrown while attemping to parse the response body, such as returning text/html when `json` was expected (which is the default parser)
- Will remain `undefined` if neither of the previous occur
- `data`
- Is `undefined` while request is pending
- Set to parsed response body (`json` by default) unless one of the `error` conditions occur
- `request`
- Set to an object containing the props passed to the component (`url`, `options`, etc) when request is sent.
- Added for convenience when `` is wrapped by your own data component (ex. ``)
- `response`
- Set to the [response](https://developer.mozilla.org/en-US/docs/Web/API/Response) of the `fetch` call
- Useful to check the status code/text, headers, etc
- `fetch`
- Function that can be called to create a new fetch request (useful when last request had an error or you want to manually refresh the data (see `manual` prop))
- The first 2 parameters match `window.fetch` (`url`, `options`). A third parameter (`updateOptions`) is available to pass options to the update phase (where `onChange`, `onDataChange`, and the child render function is called). Currently only 1 option is available (`ignorePreviousData`) which passes `undefined` as the current data (second parameter) to `onDataChange`, which is useful when using `onDataChange` to concatenate data across requests (ie. infinite loading) and the query changes
- `clearData`
- Function to clear data state.
## Examples
### Include credentials
```js
{/* ... */}
```
More interactive examples on [CodeSandbox](https://codesandbox.io/s/Z6R7OrOgQ)
## See also
- [react-odata](https://github.com/techniq/react-odata) - uses `` for OData endpoints