# react-promise-status

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

Latest version **1.0.1** (published 2019-04-30) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install react-promise-status
pnpm add react-promise-status
yarn add react-promise-status
bun add react-promise-status
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2019-04-30 |
| First published | 2019-04-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 19.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Author | André Cruz |
| Maintainers | satazor |
| Keywords | react, promise, status, timeout, delay, suspense, hook |

## Links

- npm: https://www.npmjs.com/package/react-promise-status
- Repository: https://github.com/moxystudio/react-promise-status
- Homepage: https://github.com/moxystudio/react-promise-status#readme
- Issues: https://github.com/moxystudio/react-promise-status/issues
- npm.io page: https://npm.io/package/react-promise-status

## Dependencies (3)

- [delay](https://npm.io/package/delay.md) ^4.2.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.11
- [prop-types](https://npm.io/package/prop-types.md) ^15.7.2

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.0.1 (latest) — 2019-04-30
- 1.0.0 — 2019-04-30
- 0.1.0 — 2019-04-30

## README

# react-promise-status

[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coverage Status][codecov-image]][codecov-url] [![Dependency status][david-dm-image]][david-dm-url] [![Dev Dependency status][david-dm-dev-image]][david-dm-dev-url]

[npm-url]:https://npmjs.org/package/react-promise-status
[downloads-image]:http://img.shields.io/npm/dm/react-promise-status.svg
[npm-image]:http://img.shields.io/npm/v/react-promise-status.svg
[travis-url]:https://travis-ci.org/moxystudio/react-promise-status
[travis-image]:http://img.shields.io/travis/moxystudio/react-promise-status/master.svg
[codecov-url]:https://codecov.io/gh/moxystudio/react-promise-status
[codecov-image]:https://img.shields.io/codecov/c/github/moxystudio/react-promise-status/master.svg
[david-dm-url]:https://david-dm.org/moxystudio/react-promise-status
[david-dm-image]:https://img.shields.io/david/moxystudio/react-promise-status.svg
[david-dm-dev-url]:https://david-dm.org/moxystudio/react-promise-status?type=dev
[david-dm-dev-image]:https://img.shields.io/david/dev/moxystudio/react-promise-status.svg

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


## Installation

```sh
$ 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**:

```js
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**:

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

## API

- [`<PromiseStatus>`](#promisestatus)
- [`usePromiseStatus(promise, [options])`](#usepromisestatuspromise-options)

### PromiseStatus

The `<PromiseStatus>` component allows you to conditionally render children based on the promise status and fulfillment/rejection value. It leverages the [render props](https://reactjs.org/docs/render-props.html) technique to know what to render.

#### Props

##### promise

Type: `Promise`

The promise to use.

##### children

A render prop function with the following signature:

```js
(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`](#delayms), [`resetFulfilledDelayMs`](#resetfulfilleddelayms) and [`resetRejectedDelayMs`](#resetrejecteddelayms) props for more info.

##### statusMap

Type: `object`

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

```js
{
    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`](#statusmap), [`delayMs`](#delayms), [`resetFulfilledDelayMs`](#resetfulfilleddelayms) and [`resetRejectedDelayMs`](#resetrejecteddelayms).


## Tests

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


## License

Released under the [MIT License](http://www.opensource.org/licenses/mit-license.php).

---
_Source: https://npm.io/package/react-promise-status · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._