<!---
THIS IS AN AUTOGENERATED FILE. EDIT PACKAGES/BOUNDLESS-ASYNC/INDEX.JS INSTEAD.
-->
# Async

There are plenty of situations where you need to fetch content to be displayed, but want
to show some sort of loading graphic in the interim. This component helps to simplify
that pattern by handling common types of promises and providing a simple mechanism
for materializing the fulfilled payload into JSX.

## Installation

```bash
npm i boundless-async --save
```

Then use it like:


```js
import Async from 'boundless-async';
```


Async can also just be directly used from the main [Boundless library](https://www.npmjs.com/package/boundless). This is recommended when you're getting started to avoid maintaining the package versions of several components:

```bash
npm i boundless --save
```

the ES6 `import` statement then becomes like:

```js
import { Async } from 'boundless';
```


## Props

> Note: only top-level props are in the README, for the full list check out the [website](https://boundless.js.org/Async).

### Required Props

- __`children`__ &middot; a promise, function that returns a promise, or other type of renderable content; if a function is passed, it will
  be called with the current props
  
  Promise example:
  
  ```jsx
  const listDataPromise = fetch('/some/list/data/endpoint').then(
      (response) => response.ok ? response.json() : 'Failed to receive list data',
      (error) => error.message,
  ).then((payload) => {
      if (typeof payload === 'string') {
          return (<div className='error'>{payload}</div>);
      }
  
      return (
          <ul>
              {payload.map((item) => (<li key={item.id}>{item.content}</li>))}
          </ul>
      );
  });
  
  <Async>{listDataPromise}</Async>
  ```
  
  Function example, reading in `[data-endpoint]` as the `window.fetch()` target:
  
  ```jsx
  const fetchListData = (props) => fetch(props['data-endpoint']).then(
      (response) => response.ok ? response.json() : 'Failed to receive list data',
      (error) => error.message,
  ).then((payload) => {
      if (typeof payload === 'string') {
          return (<div className='error'>{payload}</div>);
      }
  
      return (
          <ul>
              {payload.map((item) => (<li key={item.id}>{item.content}</li>))}
          </ul>
      );
  });
  
  <Async data-endpoint='/some/list/data/endpoint'>{fetchListData}</Async>
  ```

  Expects | Default Value
  ---     | ---
  `function or any renderable or Promise` | `<div />`


### Optional Props

- __`*`__ &middot; any [React-supported attribute](https://facebook.github.io/react/docs/tags-and-attributes.html#html-attributes)

  Expects | Default Value
  ---     | ---
  `any` | `n/a`

- __`childrenDidRender`__ &middot; a callback for when real content has been rendered; this will be called immediately if normal JSX is passed to Async, or, in the case of a promise, upon resolution or rejection

  Expects | Default Value
  ---     | ---
  `function` | `() => {}`

- __`pendingContent`__ &middot; content to be shown while the promise is in "pending" state (like a loading graphic, perhaps)

  Expects | Default Value
  ---     | ---
  `any renderable` | `<div />`


## Reference Styles
### Stylus
You can see what variables are available to override in [variables.styl](https://github.com/enigma-io/boundless/blob/master/variables.styl).

```stylus
// Redefine any variables as desired, e.g:
color-accent = royalblue

// Bring in the component styles; they will be autoconfigured based on the above
@require "node_modules/boundless-async/style"
```

### CSS
If desired, a precompiled plain CSS stylesheet is available for customization at `/build/style.css`, based on Boundless's [default variables](https://github.com/enigma-io/boundless/blob/master/variables.styl).