Getting Started

Introduction

Optimistic UIs are all around us. Ever clicked the Twitter Like Button? It instantly turns red to show you that the webapp has registered your click. Due to such optimistic micro-interactions the whole web-app feels blazing fast. It is crucial for the app to respond quickly to user interactions.

For some interactions like posting a tweet or following a person, showing a loader is enough. But for small actions such as liking a Tweet, adding an item to Favorites, an Optimistic Toggle offers the ideal UX. But implementing such a component is more difficult than you think.

Hint- Imagine what happens when user rapidly clicks the button multiple times and some API requests fails and some do not.

You don't have to worry though because the best Optimistic Toggle out there is just an npm install away. You can use it as a React custom hook or a render prop.

Installation

npm install react-optimistic-toggle

Examples

OptimisticToggle

import OptimisticToggle from 'react-optimistic-toggle/OptimisticToggle';

Prop name	Type	Default	Description
`action`	function	Function	On-change handler that returns a Promise Object
`children`	React.ReactNode	`noop`	UI Component that has been passed as children
`initialValue`	boolean	`false`	Initial Value of the Checkbox

Basic Usage

function action(toggledValue, event) {
  // must return a promise.
}

<OptimisticToggle action={action}>
  {(toggle, setToggle) => (
    <input type="checkbox" checked={toggle} onChange={setToggle} />
  )}
</OptimisticToggle>

Examples

Optimistic Toggle where the promise returned by action fails

After the 400ms the checkbox will get unchecked no matter how many times you check or uncheck it.

If you check or uncheck the checkbox that state will be reverted to the previous state after 400ms because the promise gets rejected.

Optimistic Toggle where the promise returned by action succeeds

the checkbox will not get unchecked later.

When you first click the checkbox, action function is called and so the promise starts executing. Before it completes if the checkbox is clicked again then more promises will be queued. Because in this case all promises will resolve successfully whatever the last action was it will be persisted in checkbox state. So if atlast you unchecked the checkbox then the checkbox will remain unchecked.

useOptimisticToggle

import useOptimisticToggle from 'react-optimistic-toggle/useOptimisticToggle';

Basic Usage

function action(toggledValue, event) {
  // must return a promise.
}

const [toggle, setToggle] = useOptimisticToggle({ initialValue, action });

Working Example

Optimistic Toggle where the promise returned by action fails

After the 400ms the checkbox will get unchecked no matter how many times you check or uncheck it.

If you check or uncheck the checkbox that state will be reverted to the previous state after 400ms because the promise gets rejected.

Optimistic Toggle where the promise returned by action succeeds

the checkbox will not get unchecked later.

Util

import util from 'react-optimistic-toggle/util';