use-optimistic-update
Improve perceived performance by predicting the future outcome
A set of utilities to achieve Optimistic UI effect. Helps to bridge the gap between async state changes.
Example
Converting async counter to optimistic component that reacts to user actions instantly:
import React, { useState } from 'react';+ import { useOptimisticUpdate } from "use-optimistic-update"; export default function UpTo3Counter() { const [counter, setCounter] = useState(0);+ const { value, onUpdate } = useOptimisticUpdate("count3r", counter); const increment = (value) => new Promise((resolve) => { setTimeout(() => { if (value <= 3) setCounter(value); resolve(); }, 1000); }); return ( <button onClick={() => { const newValue = counter + 1;- increment(newValue);+ onUpdate(() => increment(newValue), newValue); }} > Likes: {counter} </button> ); }
Installation
npm i use-optimistic-update
or
yarn add use-optimistic-update
Features
- shareable state between multiple components
- hooks
- direct event emitter access
- typescript support
API
useOptimisticUpdate
useOptimisticUpdate
is a hook that let's you sync and update the optimistic state.
import useOptimisticUpdate from 'use-optimistic-update'; const value onUpdate isUpdating = ;
Options
stateKey: string
- Required
realValue: string | number | boolean | undefined
- Required
Returns
-
value: string | number | boolean | undefined
- The optimistic value
-
onUpdate:updater:Promise<void>,newValue: string | number | boolean | undefinedPromise<void>
- Updater function that should be called when you want to update real and optimistic values
updater
- Async function that should perform the real value change
- While this function is executing the optimistic value is perceived
newValue
- The new optimistic value
-
isUpdating: boolean
- Is an update being performed for given
stateKey
- Is an update being performed for given
onUpdate
function
Using <button = => counter</button>
useOptimisticState
useOptimisticState
is a hook that let's you retrieve the optimistic state.
import useOptimisticState from 'use-optimistic-update'; const value isUpdating = ;
Options
stateKey: string
- Required
Returns
value: string | number | boolean | undefined
- The optimistic value
isUpdating: boolean
- Is an update being performed for given
stateKey
- Is an update being performed for given
optimist
optimist
is the underlying event emitter used by the hooks. It is responsible
for updating / syncing of optimistic / real values.
optimist.sync
Synchronize the real value with optimist
instance.
import optimist from 'use-optimistic-update'; optimist;
Options
stateKey: string
- Required
realValue: string | number | boolean | undefined
- Required
optimist.update
Update optimistic value inside the optimist
instance.
import optimist from 'use-optimistic-update'; optimist;
Options
stateKey: string
- Required
updater: () => Promise<void>
- Required
optimisticValue: string | number | boolean | undefined
- Required
optimist.update
Using import optimist from 'use-optimistic-update'; optimist;
optimist.getState
Retrieve the optimistic state.
import optimist from 'use-optimistic-update'; const value isUpdating = optimist;
Options
stateKey: string
- Required
Returns
value: string | number | boolean | undefined
- The optimistic value
isUpdating: boolean
- Is an update being performed for given
stateKey
- Is an update being performed for given
optimist.onUpdate
Retrieve the optimistic state.
import optimist from 'use-optimistic-update'; const unbind = optimist;
Options
-
stateKey: string
- Required
-
listener:void
- Required
- The function that will be called every time the optimistic state changes
Returns
unbind: () => void
- A function to remove the event listener
optimist.onUpdate
Using ;; ;
FAQ
- What is Optimistic UI?
Optimistic UI is a pattern that you can use to simulate the results of a mutation and update the UI even before receiving a response from the server.
License
MIT