use-merge-state
Version:
A useState variant hook that merges updates.
88 lines (57 loc) • 2.33 kB
Markdown
# use-merge-state
🗜️ A `useState` variant hook that merges updates from arrays, plain objects, maps or sets.
[](https://github.com/bouchenoiremarc/use-merge-state/actions/workflows/ci.yml) [](https://www.npmjs.com/package/use-merge-state) [](https://www.npmjs.com/package/use-merge-state) [](https://github.com/bouchenoiremarc/use-merge-state/blob/main/LICENSE)
## Installation
#### Skypack
```javascript
import { useMergeState } from "https://cdn.skypack.dev/use-merge-state"
```
#### Yarn
```bash
yarn add use-merge-state
```
#### npm
```bash
npm install use-merge-state
```
## Usage
Import `useMergeState`.
```typescript
import { useMergeState } from "use-merge-state"
```
Use it as a drop-in `useState` replacement.
```typescript
const [state, setState] = useMergeState([1, 2])
// state: [1, 2]
```
Setting arrays, plain objects, maps or sets will merge them with the current state instead of overriding it. Other types will be overridden similarly to `useState`.
```typescript
setState([3, 4])
// state: [1, 2, 3, 4]
```
Returning a functional update will run as expected and its result will then be merged with the current state.
```typescript
setState((previousState) =>
previousState.map((previousNumber) => previousNumber * 2)
)
// state: [1, 2, 3, 4, 2, 4, 6, 8]
```
## Options
A secondary `options` argument can be set either on instances, updates or both to tweak the behavior of `useMergeState`.
Setting `options` on a `useMergeState` instance will set options for all `setState` updates of this instance.
```typescript
const [state, setState] = useMergeState([1, 2], {
merge: false
})
```
Setting `options` on a `setState` update will override any previously set options for this specific update.
```typescript
setState([3, 4], {
merge: true
})
```
#### `merge`
```typescript
merge?: boolean = true
```
Setting `merge` to `false` will disable merging—essentially converting `useMergeState` back into `useState`.