StateBeginnerFully SSR-safehooks/state/useList.ts

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 · useList
Editor
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.ts for implementation details