boundless-async

Async

A higher-order component for rendering data that isn't ready yet.

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>
      );
  });
  

  {listDataPromise}

  Function example:

  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

// Bring in Boundless's base Stylus variables
@require "node_modules/boundless-async/variables"

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