useArray

useArray is a custom React hook for managing arrays, providing referentially stable utility functions for common operations like adding, removing, updating, and resetting elements.

Usage

import { useArray } from "hookify-react";

type User = {
  id: number;
  name: string;
};

export default function UserList() {
  const initialUsers: User[] = [
    { id: 1, name: "Alice" },
    { id: 2, name: "Bob" },
  ];

  const [users, setUsers, { push, pop, removeByIndex, updateByIndex, clear }] =
    useArray<User>(initialUsers);

  return (
    <div>
      <h2>User List</h2>
      <ul>
        {users.map((user, index) => (
          <li key={user.id}>
            {user.name}{" "}
            <button onClick={() => removeByIndex(index)}>Remove</button>
          </li>
        ))}
      </ul>

      <button
        onClick={() =>
          push({ id: users.length + 1, name: `User ${users.length + 1}` })
        }
      >
        Add User
      </button>
      <button
        onClick={() => updateByIndex(0, { id: 1, name: "Updated Alice" })}
      >
        Update First User
      </button>
      <button onClick={() => pop()}>Remove Last User</button>
      <button onClick={clear}>Clear Users</button>
    </div>
  );
}

API Reference

Parameters

Parameter	Type	Default	Description
initialValue	T[]	[]	The initial value of the array. Optional; defaults to an empty array.

Return Value

useArray returns a tuple [state, setState, methods]. All methods are referentially stable (memoized), so they are safe to pass to dependency arrays and memoized children.

Property	Type	Description
state	T[]	The current value of the array.
setState	Dispatch<SetStateAction<T[]>>	Function to manually update the state.
push	(value: T) => number	Adds a value to the end of the array and returns the new length.
pop	() => T | undefined	Removes and returns the last element of the array.
shift	() => T | undefined	Removes and returns the first element of the array.
unshift	(value: T) => number	Adds a value to the beginning of the array and returns the new length.
removeByIndex	(index: number) => void	Removes an element from the array by index.
removeByValue	(value: T) => void	Removes occurrences of a specified value from the array.
clear	() => void	Clears all elements from the array.
replace	(newArray: T[]) => void	Replaces the current array with a new array.
reset	() => void	Resets the array to its initial value.
filter	(predicate: (value: T, index: number, array: T[]) => boolean) => void	Filters the array based on a predicate function and updates the state.
updateByIndex	(index: number, value: T) => void	Updates the value of an element at a specific index.
updateByValue	(prevValue: T, newValue: T) => void	Updates occurrences of a specific value with a new value.

Behavior

• initialValue is optional and defaults to an empty array ([]).
• All returned methods are memoized and keep a stable identity across renders.
• push and unshift return the new length of the array.
• pop and shift return the removed element, or undefined when the array is empty.
• removeByValue and updateByValue compare object elements by their JSON representation and primitive elements by value.
• reset restores the array to the initialValue captured on the first render.