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.