Usage
Manages a set-like selection over a provided data collection. Includes helpers for selecting, deselecting, toggling, resetting, and checking aggregate selection state.
import { useSelection } from '@kuzenbo/hooks';
function Demo() {
const items = ['Apple', 'Banana', 'Cherry', 'Date'];
const [selection, handlers] = useSelection({ data: items });
return (
<div>
{items.map((item) => (
<div key={item}>
<input
type="checkbox"
checked={selection.includes(item)}
onChange={() => handlers.toggle(item)}
/>
<label>{item}</label>
</div>
))}
<p>Selected: {selection.join(', ')}</p>
</div>
);
}
Select all / deselect all
Use the provided helpers to check and manage bulk selection:
import { useSelection } from '@kuzenbo/hooks';
function Demo() {
const items = ['Item 1', 'Item 2', 'Item 3'];
const [selection, handlers] = useSelection({ data: items });
const handleSelectAll = () => {
if (handlers.isAllSelected()) {
handlers.resetSelection();
} else {
handlers.setSelection(items);
}
};
return (
<div>
<div>
<input
type="checkbox"
checked={handlers.isAllSelected()}
indeterminate={handlers.isSomeSelected() && !handlers.isAllSelected()}
onChange={handleSelectAll}
/>
<label>Select All</label>
</div>
{items.map((item) => (
<div key={item}>
<input
type="checkbox"
checked={selection.includes(item)}
onChange={() => handlers.toggle(item)}
/>
<label>{item}</label>
</div>
))}
</div>
);
}
With default selection
Provide initial selected items:
import { useSelection } from '@kuzenbo/hooks';
function Demo() {
const items = ['Red', 'Green', 'Blue'];
const [selection, handlers] = useSelection({
data: items,
defaultSelection: ['Red', 'Blue'],
});
return (
<div>
{items.map((item) => (
<div key={item}>
<input
type="checkbox"
checked={selection.includes(item)}
onChange={() => handlers.toggle(item)}
/>
<label>{item}</label>
</div>
))}
</div>
);
}
Reset on data change
Clear selection when data changes:
import { useSelection } from '@kuzenbo/hooks';
import { useState } from 'react';
function Demo() {
const [dataSet, setDataSet] = useState<string[]>(['A', 'B', 'C']);
const [selection, handlers] = useSelection({
data: dataSet,
resetSelectionOnDataChange: true,
});
return (
<div>
<button onClick={() => setDataSet(['X', 'Y', 'Z'])}>
Load New Data
</button>
{dataSet.map((item) => (
<div key={item}>
<input
type="checkbox"
checked={selection.includes(item)}
onChange={() => handlers.toggle(item)}
/>
<label>{item}</label>
</div>
))}
</div>
);
}
Definition
interface UseSelectionInput<T> {
data: T[];
defaultSelection?: T[];
resetSelectionOnDataChange?: boolean;
}
interface UseSelectionHandlers<T> {
select: (selected: T) => void;
deselect: (deselected: T) => void;
toggle: (toggled: T) => void;
isAllSelected: () => boolean;
isSomeSelected: () => boolean;
setSelection: (selection: T[]) => void;
resetSelection: () => void;
}
type UseSelectionReturnValue<T> = readonly [
T[],
UseSelectionHandlers<T>
]
function useSelection<T>(
input: UseSelectionInput<T>
): UseSelectionReturnValue<T>
Parameters
Source items that selection state is evaluated against
Items selected on first render
resetSelectionOnDataChange
Clears selection whenever data changes when enabled
Returns
Returns a tuple [selection, handlers]:
Array of currently selected items
Object containing selection management functions:
select(item: T): Add an item to the selectiondeselect(item: T): Remove an item from the selectiontoggle(item: T): Toggle an item’s selection stateisAllSelected(): Returns true if all items from data are selectedisSomeSelected(): Returns true if at least one item from data is selectedsetSelection(selection: T[]): Set the selection to a specific array of itemsresetSelection(): Clear all selections