boundless-async

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

npm i boundless-async --save

Then use it like:

import Async from 'boundless-async';

Async can also just be directly used from the main Boundless library. This is recommended when you're getting started to avoid maintaining the package versions of several components:

npm i boundless --save

the ES6 import statement then becomes like:

import { Async } from 'boundless';

Props

Note: only top-level props are in the README, for the full list check out the website.

Required Props

• children · 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:

  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:

  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

• * · any React-supported attribute

  Expects	Default Value
  any	n/a

• childrenDidRender · 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 · 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.

// 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.