react-promise-status

A React component and hook to render children conditionally based on a promise status.

Installation

$ npm install react-promise-status

This library is written in modern JavaScript and is published in both CommonJS and ES module transpiled variants. If you target older browsers please make sure to transpile accordingly.

Usage

With <PromiseStatus> component:

import React, { useMemo, useState } from 'react';
import { PromiseStatus } from 'react-promise-status';
 
const SomeComponent = (props) => {
    const [savePromise, setSavePromise] = useState();
    const handleSave = useMemo(
        () => () => setSavePromise(props.save()),
        [props.save]
    );
 
    return (
        <div>
            <button onSave={ handleSave }>Save</button>
            <PromiseStatus promise={ savePromise }>
                { (status) => (
                    <p>
                        { status === 'pending' && 'Saving..' }
                        { status === 'fulfilled' && 'Saved!' }
                        { status === 'rejected' && 'Oops, failed to save' }
                    </p>
                ) }
            </PromiseStatus>
        </div>
    );
}

With usePromiseStatus() hook:

import React, { useMemo, useState } from 'react';
import { usePromiseStatus } from 'react-promise-status';
 
const SomeComponent = (props) => {
    const [savePromise, setSavePromise] = useState();
    const [saveStatus] = usePromiseStatus(savePromise);
    const handleSave = useMemo(
        () => () => setSavePromise(props.save()),
        [props.save]
    );
 
    return (
        <div>
            <button onSave={ handleSave }>Save</button>
            <p>
                { saveStatus === 'pending' && 'Saving..' }
                { saveStatus === 'fulfilled' && 'Saved!' }
                { saveStatus === 'rejected' && 'Oops, failed to save' }
            </p>
        </div>
    );
}

PromiseStatus

The <PromiseStatus> component allows you to conditionally render children based on the promise status and fulfillment/rejection value. It leverages the render props technique to know what to render.

Props

promise

Type: Promise

The promise to use.

children

A render prop function with the following signature:

(status, value) => {}

The status argument is one of none, pending, rejected, fulfilled. The value argument is either the fulfillment value or the rejection value.

The none status only happens when there's no promise or when reset. Please see delayMs, resetFulfilledDelayMs and resetRejectedDelayMs props for more info.

statusMap

Type: object

An object to map status, useful when you want to use other names:

{
    pending: 'loading',
    fulfilled: 'success',
    rejected: 'error',
}

You may omit statuses you don't want to map and the default ones will be used.

delayMs

Type: Number
Default: 0 (disabled)

The delay in ms to wait for the promise to settle before changing status to pending. Useful if you want to render a loading only when the promise is taking some time.

When a delayMs is specified an when the promise prop changes from undefined to a promise, the status will be none during the specified delay and changes to pending afterwards.

resetFulfilledDelayMs

Type: Number
Default: 0 (disabled)

The delay in ms to change the status to none after the promise fulfills. Useful if you no longer want to render a success message after a certain time.

resetRejectedDelayMs

Type: Number
Default: 0 (disabled)

The delay in ms to change the status to none after the promise rejects. Useful if you no longer want to render an error message after a certain time.

usePromiseStatus(promise, [options])

The hook version of the <PromiseStatus> component.

Returns an array with [status, value].

The options are the same as the <PromiseStatus>'s props counterparts: statusMap, delayMs, resetFulfilledDelayMs and resetRejectedDelayMs.

Tests

$ npm test
$ npm test -- --watch # during development

License

Released under the MIT License.

npm

This package has been deprecated