useSet

state

Installation

npx usehooks-cli@latest add use-set

Description

A React hook that provides a stateful Set with comprehensive methods for manipulation. Offers all standard Set operations plus additional utilities like filtering, set operations, and array conversion.

Parameters

Name	Type	Default	Description
initialValues?	T[] \| Set<T>	-	Initial values for the Set (array or existing Set)

Return Type

UseSetReturn<T>

Property	Type	Description
set	Set<T>	The current Set instance
add	(value: T) => void	Add a single value to the Set
addMultiple	(...values: T[]) => void	Add multiple values to the Set
remove	(value: T) => boolean	Remove a value from the Set, returns true if removed
removeMultiple	(...values: T[]) => void	Remove multiple values from the Set
clear	() => void	Remove all values from the Set
has	(value: T) => boolean	Check if the Set contains a value
toggle	(value: T) => void	Add value if not present, remove if present
replace	(oldValue: T, newValue: T) => boolean	Replace an old value with a new value
filter	(predicate: (value: T) => boolean) => void	Filter the Set based on a predicate function
union	(otherSet: Set<T> \| T[]) => void	Add all values from another Set or array
intersection	(otherSet: Set<T> \| T[]) => void	Keep only values that exist in both Sets
difference	(otherSet: Set<T> \| T[]) => void	Remove values that exist in another Set
isSubsetOf	(otherSet: Set<T> \| T[]) => boolean	Check if this Set is a subset of another
isSupersetOf	(otherSet: Set<T> \| T[]) => boolean	Check if this Set is a superset of another
toArray	() => T[]	Convert the Set to an array
reset	() => void	Reset the Set to its initial values
size	number	Current number of values in the Set
isEmpty	boolean	Whether the Set is empty

Examples

Managing a Set of tags

import { useSet } from '@usehooks.io/use-set';

function TagManager() {
  const {
    set: tags,
    add,
    remove,
    toggle,
    clear,
    has,
    size,
    isEmpty,
    toArray
  } = useSet(['react', 'typescript']);

  return (
    <div>
      <p>Tags ({size}): {isEmpty ? 'None' : toArray().join(', ')}</p>
      
      <button onClick={() => add('javascript')}>
        Add JavaScript
      </button>
      
      <button onClick={() => toggle('vue')}>
        Toggle Vue
      </button>
      
      <button onClick={() => remove('react')}>
        Remove React
      </button>
      
      <button onClick={clear}>
        Clear All
      </button>
      
      <p>Has React: {has('react') ? 'Yes' : 'No'}</p>
    </div>
  );
}

Dependencies

react

Notes

•Optimizes re-renders by only updating state when Set actually changes
•Supports both Set and array inputs for set operations
•All methods are memoized with useCallback for performance
•Maintains referential equality when possible to prevent unnecessary re-renders

Implementation

"use client";

import { useState, useCallback } from "react";

interface UseSetReturn<T> {
  set: Set<T>;
  add: (value: T) => void;
  addMultiple: (...values: T[]) => void;
  remove: (value: T) => boolean;
  removeMultiple: (...values: T[]) => void;
  clear: () => void;
  has: (value: T) => boolean;
  toggle: (value: T) => void;
  replace: (oldValue: T, newValue: T) => boolean;
  filter: (predicate: (value: T) => boolean) => void;
  union: (otherSet: Set<T> | T[]) => void;
  intersection: (otherSet: Set<T> | T[]) => void;
  difference: (otherSet: Set<T> | T[]) => void;
  isSubsetOf: (otherSet: Set<T> | T[]) => boolean;
  isSupersetOf: (otherSet: Set<T> | T[]) => boolean;
  toArray: () => T[];
  reset: () => void;
  size: number;
  isEmpty: boolean;
}

export function useSet<T>(initialValues?: T[] | Set<T>): UseSetReturn<T> {
  const [set, setSet] = useState<Set<T>>(() => {
    if (initialValues instanceof Set) {
      return new Set(initialValues);
    }
    return new Set(initialValues || []);
  });

  const add = useCallback((value: T) => {
    setSet((prev) => {
      if (prev.has(value)) return prev;
      const newSet = new Set(prev);
      newSet.add(value);
      return newSet;
    });
  }, []);

  const addMultiple = useCallback((...values: T[]) => {
    setSet((prev) => {
      const newSet = new Set(prev);
      let hasChanges = false;
      values.forEach((value) => {
        if (!newSet.has(value)) {
          newSet.add(value);
          hasChanges = true;
        }
      });
      return hasChanges ? newSet : prev;
    });
  }, []);

  const remove = useCallback((value: T): boolean => {
    let wasRemoved = false;
    setSet((prev) => {
      if (!prev.has(value)) {
        wasRemoved = false;
        return prev;
      }
      const newSet = new Set(prev);
      wasRemoved = newSet.delete(value);
      return newSet;
    });
    return wasRemoved;
  }, []);

  const removeMultiple = useCallback((...values: T[]) => {
    setSet((prev) => {
      const newSet = new Set(prev);
      let hasChanges = false;
      values.forEach((value) => {
        if (newSet.delete(value)) {
          hasChanges = true;
        }
      });
      return hasChanges ? newSet : prev;
    });
  }, []);

  const clear = useCallback(() => {
    setSet((prev) => (prev.size === 0 ? prev : new Set()));
  }, []);

  const has = useCallback(
    (value: T): boolean => {
      return set.has(value);
    },
    [set]
  );

  const toggle = useCallback((value: T) => {
    setSet((prev) => {
      const newSet = new Set(prev);
      if (newSet.has(value)) {
        newSet.delete(value);
      } else {
        newSet.add(value);
      }
      return newSet;
    });
  }, []);

  const replace = useCallback((oldValue: T, newValue: T): boolean => {
    let wasReplaced = false;
    setSet((prev) => {
      if (!prev.has(oldValue)) {
        wasReplaced = false;
        return prev;
      }
      const newSet = new Set(prev);
      newSet.delete(oldValue);
      newSet.add(newValue);
      wasReplaced = true;
      return newSet;
    });
    return wasReplaced;
  }, []);

  const filter = useCallback((predicate: (value: T) => boolean) => {
    setSet((prev) => {
      const newSet = new Set<T>();
      let hasChanges = false;
      prev.forEach((value) => {
        if (predicate(value)) {
          newSet.add(value);
        } else {
          hasChanges = true;
        }
      });
      return hasChanges ? newSet : prev;
    });
  }, []);

  const union = useCallback(
    (otherSet: Set<T> | T[]) => {
      const otherValues = Array.isArray(otherSet)
        ? otherSet
        : Array.from(otherSet);
      addMultiple(...otherValues);
    },
    [addMultiple]
  );

  const intersection = useCallback((otherSet: Set<T> | T[]) => {
    const otherSetInstance = Array.isArray(otherSet)
      ? new Set(otherSet)
      : otherSet;
    setSet((prev) => {
      const newSet = new Set<T>();
      prev.forEach((value) => {
        if (otherSetInstance.has(value)) {
          newSet.add(value);
        }
      });
      return newSet.size !== prev.size ? newSet : prev;
    });
  }, []);

  const difference = useCallback((otherSet: Set<T> | T[]) => {
    const otherSetInstance = Array.isArray(otherSet)
      ? new Set(otherSet)
      : otherSet;
    setSet((prev) => {
      const newSet = new Set<T>();
      let hasChanges = false;
      prev.forEach((value) => {
        if (!otherSetInstance.has(value)) {
          newSet.add(value);
        } else {
          hasChanges = true;
        }
      });
      return hasChanges ? newSet : prev;
    });
  }, []);

  const isSubsetOf = useCallback(
    (otherSet: Set<T> | T[]): boolean => {
      const otherSetInstance = Array.isArray(otherSet)
        ? new Set(otherSet)
        : otherSet;
      for (const value of set) {
        if (!otherSetInstance.has(value)) {
          return false;
        }
      }
      return true;
    },
    [set]
  );

  const isSupersetOf = useCallback(
    (otherSet: Set<T> | T[]): boolean => {
      const otherSetInstance = Array.isArray(otherSet)
        ? new Set(otherSet)
        : otherSet;
      for (const value of otherSetInstance) {
        if (!set.has(value)) {
          return false;
        }
      }
      return true;
    },
    [set]
  );

  const toArray = useCallback((): T[] => {
    return Array.from(set);
  }, [set]);

  const reset = useCallback(() => {
    const initialSet =
      initialValues instanceof Set
        ? new Set(initialValues)
        : new Set(initialValues || []);
    setSet(initialSet);
  }, [initialValues]);

  return {
    set,
    add,
    addMultiple,
    remove,
    removeMultiple,
    clear,
    has,
    toggle,
    replace,
    filter,
    union,
    intersection,
    difference,
    isSubsetOf,
    isSupersetOf,
    toArray,
    reset,
    size: set.size,
    isEmpty: set.size === 0,
  };
}

export default useSet;

useLocalStorage

CLI Docs All Hooks

useToggle