React component to declaratively fetch data

react-fetch-component

React component to declaratively fetch data.

Install

yarn add react-fetch-component

or

npm install --save react-fetch-component

Usage

You supply a single function as a child of <Fetch /> 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.

<Fetch url="someUrl">
  { ({ loading, error, data }) => (
    <div>
      { loading && {/* handle loading here */} }
      { error && {/* handle error here */} }
      { data && {/* handle data here */}}
    </div>
  )}
</Fetch>

You can also use React's context via <Fetch.Consumer> for accessing the state in a deep tree (or to create components based on state)

const Loading = () => <Fetch.Consumer>{({ loading }) => loading ? <MySpinner /> : null}</Fetch.Consumer>
const Error = () => <Fetch.Consumer>{({ error }) => error ? <MyError error={error} /> : null}</Fetch.Consumer>

<Fetch url="someUrl">
  <div>
    <div>
      <div>
        <Loading />
        <Error />
        <Fetch.Consumer>
          {({ data }) => <div>{ data ? /* handle data here */ : null}</div>}
        </Fetch.Consumer>
      </div>
    </div>
  </div>
</Fetch>

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 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 including:
    • arrayBuffer
    • blob
    • formData
    • json
    • text
  • or a function that takes in the response and returns a Promise. For example <Fetch as={res => 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 <Fetch as={{ 'application/json': res => 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 <Fetch /> component has been unmounted.
  • default: undefined
• fetchFunction (function) - Specify own fetch function. Useful to debounce fetch requests (although probably best to debounce outside of <Fetch /> so not call unneccessary renders)
  • default: window.fetch

Object properties passed to child function

• loading
  • Set to true while request is pending
  • Set to false once response has returned
• 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 <Fetch /> is wrapped by your own data component (ex. <UserData />)
• response
  • Set to the 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

<Fetch url="someUrl" options={{ credentials: 'include' }}>
  {/* ... */}
</Fetch>

GitHub