https://github.com/frontendphil/react-undo-redo
A utility to add undo and redo functionality to any state managed through a reducer.
https://github.com/frontendphil/react-undo-redo
hooks hooks-api react state-management undo-redo
Last synced: 5 months ago
JSON representation
A utility to add undo and redo functionality to any state managed through a reducer.
- Host: GitHub
- URL: https://github.com/frontendphil/react-undo-redo
- Owner: frontendphil
- License: apache-2.0
- Created: 2020-10-09T09:45:47.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-10-28T15:20:36.000Z (8 months ago)
- Last Synced: 2024-10-29T22:57:51.784Z (8 months ago)
- Topics: hooks, hooks-api, react, state-management, undo-redo
- Language: TypeScript
- Homepage: https://react-undo-redo.vercel.app/
- Size: 1.83 MB
- Stars: 26
- Watchers: 3
- Forks: 4
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# react-undo-redo
A utility to add undo and redo functionality to any state managed through a reducer.
This library **does not** require [`redux`](https://redux.js.org/).
If you're looking for something that adds undo and redo to a state that is managed through `redux` you might be in the wrong place.
## Installation
Through [`yarn`](https://yarnpkg.com/).
```sh
yarn add react-undo-redo
```
Through [`npm`](https://www.npmjs.com/)
```sh
npm install --save react-undo-redo
```
## Usage
In order to create the provider and hooks to manage undo and redo you call `createUndoRedo` and pass the `reducer` you'd like to enhance.
This method returns a provider component and hooks to work with your state.
The `reducer` you pass does not need any knowledge about this feature.
```js
import { createUndoRedo } from "react-undo-redo"
const { UndoRedoProvider, usePast, usePresent, useFuture, useUndoRedo } =
createUndoRedo(reducer)
```
`createUndoRedo` also accepts an options object as a second parameter. Currently available options:
- `track` - function with signature `(action) => boolean`. It is invoked on every dispatch and defines whether the new state is avaiable for undo/redo. If function returns `false`, the state won't affect the change history. It is useful in situations, when the change is not reflected in the UI or the user cannot control over.
```js
import { createUndoRedo } from "react-undo-redo"
const { UndoRedoProvider, usePast, usePresent, useFuture, useUndoRedo } =
createUndoRedo(reducer, {track: (action) => action.type !== 'GET_NEW_TODOS'})
```
### `UndoRedoProvider`
| Prop | Required | Description |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `initialState` | ✔️ | The initial state that your reducer needs. This does **not** need any notion of past, present, or future. |
| `past` | | If you like to restore a prior session you can pass an earlier version of past states here. |
| `future` | | If you like to restore a prior session you can pass an earlier version of future states here. |
```js
function Component() {
return (
)
}
```
### `usePresent` => `[state, dispatch]`
The return value of this hook mimics the [`useReducer`](https://reactjs.org/docs/hooks-reference.html#usereducer) hook.
You get access to the current present state.
Use the `dispatch` method to dispatch any of your actions.
```js
function Component() {
const [count, dispatch] = usePresent()
return (
<>
count: {count}
dispatch({ type: "increment" })}>Add 1
>
)
}
```
### `useUndoRedo` => `[undo, redo]`
Returns a tuple that contains methods to signal `undo` or `redo`.
If you call the two methods `react-undo-redo` updates the current `present` state.
**Important**: You can also call `undo` or `redo` when there is nothing to undo or redo.
However, you can check whether there is anything to undo or redo by checking the `isPossible` prop that is present on both methods.
```js
function Component() {
const [undo, redo] = useUndoRedo()
return (
<>
undo()}>
Undo
redo()}>
Redo
>
)
}
```
### `usePast` => `[...state]`
Returns all current past states (i.e. state snapshots when actions are dispatched).
You probably don't need to use this.
### `useFuture` => `[...state]`
Returns all current future states (i.e. states that have been undone).
You probably don't need to use this.