useArray

state

Installation

npx usehooks-cli@latest add use-array

Description

A powerful React hook that provides helper methods for working with array state, including push, pop, filter, sort, and other common array operations with optimized performance using useCallback.

Parameters

Name	Type	Default	Description
initialArray?	T[]	[]	The initial array value to start with

Return Type

UseArrayReturn<T>

Property	Type	Description
array	T[]	The current array state
set	(newArray: T[]) => void	Replace the entire array with a new array
push	(...items: T[]) => void	Add one or more items to the end of the array
pop	() => T \| undefined	Remove and return the last item from the array
shift	() => T \| undefined	Remove and return the first item from the array
unshift	(...items: T[]) => void	Add one or more items to the beginning of the array
insert	(index: number, ...items: T[]) => void	Insert one or more items at a specific index
remove	(index: number) => void	Remove an item at a specific index
removeById	(id: any, key?: keyof T) => void	Remove an item by its ID or specified key
update	(index: number, item: T) => void	Update an item at a specific index
updateById	(id: any, updates: Partial<T>, key?: keyof T) => void	Update an item by its ID or specified key with partial updates
clear	() => void	Remove all items from the array
filter	(predicate: (item: T, index: number) => boolean) => void	Filter the array in place using a predicate function
sort	(compareFn?: (a: T, b: T) => number) => void	Sort the array in place

Examples

Basic Array Operations

Managing a list of items with common operations

const { array, push, pop, remove, clear } = useArray([1, 2, 3]);

return (
  <div>
    <p>Array: {JSON.stringify(array)}</p>
    <button onClick={() => push(array.length + 1)}>Add Item</button>
    <button onClick={pop}>Remove Last</button>
    <button onClick={() => remove(0)}>Remove First</button>
    <button onClick={clear}>Clear All</button>
  </div>
);

Dependencies

react

Notes

•All mutation methods are memoized with useCallback for performance
•Supports generic types for type-safe array operations
•Provides both index-based and ID-based operations
•Maintains referential equality for unchanged arrays

Implementation

"use client";

import { useState, useCallback } from "react";

interface UseArrayReturn<T> {
  array: T[];
  set: (newArray: T[]) => void;
  push: (...items: T[]) => void;
  pop: () => T | undefined;
  shift: () => T | undefined;
  unshift: (...items: T[]) => void;
  insert: (index: number, ...items: T[]) => void;
  remove: (index: number) => void;
  removeById: (id: any, key?: keyof T) => void;
  update: (index: number, item: T) => void;
  updateById: (id: any, item: Partial<T>, key?: keyof T) => void;
  clear: () => void;
  filter: (predicate: (item: T, index: number) => boolean) => void;
  sort: (compareFn?: (a: T, b: T) => number) => void;
  reverse: () => void;
  replace: (oldItem: T, newItem: T) => void;
  toggle: (item: T) => void;
  isEmpty: boolean;
  length: number;
}

export function useArray<T>(initialArray: T[] = []): UseArrayReturn<T> {
  const [array, setArray] = useState<T[]>(initialArray);

  const set = useCallback((newArray: T[]) => {
    setArray(newArray);
  }, []);

  const push = useCallback((...items: T[]) => {
    setArray((prev) => [...prev, ...items]);
  }, []);

  const pop = useCallback((): T | undefined => {
    let poppedItem: T | undefined;
    setArray((prev) => {
      if (prev.length === 0) return prev;
      poppedItem = prev[prev.length - 1];
      return prev.slice(0, -1);
    });
    return poppedItem;
  }, []);

  const shift = useCallback((): T | undefined => {
    let shiftedItem: T | undefined;
    setArray((prev) => {
      if (prev.length === 0) return prev;
      shiftedItem = prev[0];
      return prev.slice(1);
    });
    return shiftedItem;
  }, []);

  const unshift = useCallback((...items: T[]) => {
    setArray((prev) => [...items, ...prev]);
  }, []);

  const insert = useCallback((index: number, ...items: T[]) => {
    setArray((prev) => {
      const newArray = [...prev];
      newArray.splice(index, 0, ...items);
      return newArray;
    });
  }, []);

  const remove = useCallback((index: number) => {
    setArray((prev) => {
      if (index < 0 || index >= prev.length) return prev;
      return prev.filter((_, i) => i !== index);
    });
  }, []);

  const removeById = useCallback((id: any, key: keyof T = "id" as keyof T) => {
    setArray((prev) => prev.filter((item) => item[key] !== id));
  }, []);

  const update = useCallback((index: number, item: T) => {
    setArray((prev) => {
      if (index < 0 || index >= prev.length) return prev;
      const newArray = [...prev];
      newArray[index] = item;
      return newArray;
    });
  }, []);

  const updateById = useCallback(
    (id: any, updates: Partial<T>, key: keyof T = "id" as keyof T) => {
      setArray((prev) =>
        prev.map((item) => (item[key] === id ? { ...item, ...updates } : item))
      );
    },
    []
  );

  const clear = useCallback(() => {
    setArray([]);
  }, []);

  const filter = useCallback(
    (predicate: (item: T, index: number) => boolean) => {
      setArray((prev) => prev.filter(predicate));
    },
    []
  );

  const sort = useCallback((compareFn?: (a: T, b: T) => number) => {
    setArray((prev) => [...prev].sort(compareFn));
  }, []);

  const reverse = useCallback(() => {
    setArray((prev) => [...prev].reverse());
  }, []);

  const replace = useCallback((oldItem: T, newItem: T) => {
    setArray((prev) => {
      const index = prev.indexOf(oldItem);
      if (index === -1) return prev;
      const newArray = [...prev];
      newArray[index] = newItem;
      return newArray;
    });
  }, []);

  const toggle = useCallback((item: T) => {
    setArray((prev) => {
      const index = prev.indexOf(item);
      if (index === -1) {
        return [...prev, item];
      } else {
        return prev.filter((_, i) => i !== index);
      }
    });
  }, []);

  return {
    array,
    set,
    push,
    pop,
    shift,
    unshift,
    insert,
    remove,
    removeById,
    update,
    updateById,
    clear,
    filter,
    sort,
    reverse,
    replace,
    toggle,
    isEmpty: array.length === 0,
    length: array.length,
  };
}

export default useArray;

CLI Docs All Hooks

useCounter