README.md

🔄 use-enhanced-state

A collection of enhanced useState hooks for React.

Table of contents

• Installation
• Hooks
  • useControlledState
  • useListState
  • useBoolState
  • useLocalState

Installation

npm install --save use-enhanced-state

Hooks

useControlledState

Used to sync local component state and incoming state from props. This is useful for creating controlled components, like a custom <Input />.

import React from 'react';
import { useControlledState } from 'use-enhanced-state';

const Control = ({ value: valueProp }) => {
	const [value, setValue] = useControlledState(valueProp);

	return <Input value={value} onChange={setValue} />;
};

useControlledState(initialState?: any, { initial?: any })

useControlledState has options as a second argument. initial from options can be used to set the initial value for the internal controlled state.

useListState

Used for a flat array.

import React from 'react';
import { useListState } from 'use-enhanced-state';

const ListComponent = () => {
	const [items, itemsFns] = useListState([{ id: 1 }, { id: 2 }]);

	return (
		<ul>
			{items.map((item) => (
				<li key={item.id}>{item.id}</li>
			))}
		</ul>
	);
};

Methods

There are a handful of convenient methods provided by the second argument of useListState().

.add(data)

Alias: .append()

Adds a new item to the array (at the end).

const [items, itemsFns] = useListState([...]);

itemsFns.add({ id: 'a' });

.find({ at: number, id: any })

Alias: .get()

Finds an item from the array, using either an index value (at) or an id.

const [items, itemsFns] = useListState([...]);

itemsFns.find({ id: 'a' });
itemsFns.find({ at: 9 });

.has({ at: number, id: any })

Checks to see if the array contains an item.

const [items, itemsFns] = useListState([...]);

itemsFns.has({ id: 'a' });

.indexOf({ id: any })

Checks an index of an item based on an id.

const [items, itemsFns] = useListState([...]);

itemsFns.indexOf({ id: 'a' });

.insert({ at: number, item: any })

Adds new data an a specific index.

const [items, itemsFns] = useListState([...]);

itemsFns.insert({at: 3, item: { id: 'a' }});

.move(source: number, destination: number)

Moves an item from a previous index (source) to a new index (destination).

const [items, itemsFns] = useListState([...]);

itemsFns.move(3, 5);

.prepend(data)

Adds a new item to the array (at the start).

const [items, itemsFns] = useListState([...]);

itemsFns.prepend({ id: 'a' });

.remove({ at: number, id: any })

Removes an item from the array, given an index value (at) or an id. Alternatively, a filter match (function) can be provided.

const [items, itemsFns] = useListState([...]);

itemsFns.remove({ id: 'a' });
// or
itemsFns.remove((item) => item.id === 'a');

.removeAll((item: any, index: number) => boolean)

Removes all items from the array based on a filter match.

const [items, itemsFns] = useListState([...]);

itemsFns.removeAll((item) => item.value > 50);

.set(Array | Function)

Alias: .setState()

The original React setState callback from useState.

const [items, itemsFns] = useListState([...]);

itemsFns.set([{ id: 'a' }]);

.update(Object)

Updating an item based on an id match.

const [items, itemsFns] = useListState([...]);

itemsFns.update({ id: 'a', title: 'b' });

useBoolState

Used for a boolean state.

import React from 'react';
import { useListState } from 'use-enhanced-state';

const ListComponent = () => {
	const [show, showData] = useBoolState(false);

	return <div>{show ? 'Show' : 'Hide'}</div>;
};

Methods

There are a handful of convenient methods provided by the second argument of useBoolState().

.true()

Alias: .truthy()

Sets the value to true.

const [value, valueFns] = useBoolState(false);

valueFns.true();

.false()

Alias: .falsy()

Sets the value to false.

const [value, valueFns] = useBoolState(true);

valueFns.false();

.toggle()

Toggles the value between true and false.

const [value, valueFns] = useBoolState(true);

valueFns.toggle();

.set(Array | Function)

Alias: .setState()

The original React setState callback from useState.

const [value, valueFns] = useBoolState(false);

valueFns.set(true);

useLocalState

Used to read/write state to localStorage.

import React from 'react';
import { useListState } from 'use-enhanced-state';

const ListComponent = () => {
	const [config, setConfig] = useLocalState('items', {...});

	return (
		<div>{config.dark ? 'Dark' : 'Light'}</div>
	);
};

useLocalState(key: string, state: any)

The key will be used as the localState key for your data.