useList
Array helpers: push, remove, sort, filter, reset.
Import
TypeScript
import { useList } from '@/hooks';API
Signature
useList<T>(initial?) → [list, actions]
When to use
Use useList instead of re-implementing the same pattern in multiple components.
SSR / Next.js
Fully SSR-safe. Pure React state.
Live playground
Edit the example and see it run against the real @/hooks package in this app.
Live playgroundEdit · run with real
@/hooks · useListEditor
function Todos() { const [items, list] = useList<string>(['Ship hooks']); return ( <div> <button onClick={() => list.push('New item')}>Add</button> <button onClick={() => list.removeAt(0)}>Remove first</button> <button onClick={list.clear}>Clear</button> <ul>{items.map((t, i) => <li key={i}>{t}</li>)}</ul> </div> ); }
Preview
Implementation source
Full library source for useList — copy into your project when you are not installing a package yet.
hooks/state/useList.ts
import { useCallback, useRef, useState } from 'react';
export interface UseListActions<T> {
set: (list: T[] | ((prev: T[]) => T[])) => void;
push: (...items: T[]) => void;
insertAt: (index: number, item: T) => void;
updateAt: (index: number, item: T) => void;
removeAt: (index: number) => void;
clear: () => void;
reset: () => void;
filter: (predicate: (item: T, index: number) => boolean) => void;
sort: (compareFn?: (a: T, b: T) => number) => void;
}
/** Array/list state with immutable helpers. */
export function useList<T>(
initialList: T[] | (() => T[]) = [],
): [T[], UseListActions<T>] {
const [list, setList] = useState(initialList);
const initialRef = useRef(initialList);
const set = setList;
const push = useCallback((...items: T[]) => {
setList((prev) => [...prev, ...items]);
}, []);
const insertAt = useCallback((index: number, item: T) => {
setList((prev) => {
const next = [...prev];
next.splice(index, 0, item);
return next;
});
}, []);
const updateAt = useCallback((index: number, item: T) => {
setList((prev) => {
if (index < 0 || index >= prev.length) return prev;
const next = [...prev];
next[index] = item;
return next;
});
}, []);
const removeAt = useCallback((index: number) => {
setList((prev) => prev.filter((_, i) => i !== index));
}, []);
const clear = useCallback(() => setList([]), []);
const reset = useCallback(() => {
const initial = initialRef.current;
setList(typeof initial === 'function' ? (initial as () => T[])() : initial);
}, []);
const filter = useCallback((predicate: (item: T, index: number) => boolean) => {
setList((prev) => prev.filter(predicate));
}, []);
const sort = useCallback((compareFn?: (a: T, b: T) => number) => {
setList((prev) => [...prev].sort(compareFn));
}, []);
return [
list,
{ set, push, insertAt, updateAt, removeAt, clear, reset, filter, sort },
];
}
Copy-paste example
useList.example.tsx
'use client';
import { useList } from '@/hooks';
export function Todos() {
const [items, list] = useList<string>(['Ship hooks']);
return (
<div>
<button onClick={() => list.push('New item')}>Add</button>
<button onClick={() => list.removeAt(0)}>Remove first</button>
<button onClick={list.clear}>Clear</button>
<ul>{items.map((t, i) => <li key={i}>{t}</li>)}</ul>
</div>
);
}Production checklist
- Called only from Client Components or other custom hooks
- Type parameters filled in (e.g.
useFetch<User[]>) - Tip: Keep state setters stable; prefer action helpers over manual setState spreads.
- Source of truth: open
hooks/state/useList.tsfor implementation details