useSymbol

utility

Installation

npx usehooks-cli@latest add use-symbol

Description

A React hook that provides utilities for creating and managing JavaScript Symbols. Symbols are primitive values that are guaranteed to be unique and are often used as unique property keys that won't collide with other code. This hook offers symbol creation, global registry management, and access to well-known symbols.

Return Type

UseSymbolReturn

Property	Type	Description
createSymbol	(description?: string) => symbol	Creates a new unique symbol with optional description
getGlobalSymbol	(key: string) => symbol	Gets or creates a symbol from the global symbol registry
getSymbolKey	(symbol: symbol) => string \| undefined	Gets the key for a symbol in the global registry
isSymbol	(value: any) => value is symbol	Type guard to check if a value is a symbol
getDescription	(symbol: symbol) => string \| undefined	Gets the description of a symbol
wellKnownSymbols	object	Object containing all well-known symbols (iterator, hasInstance, etc.)
symbols	symbol[]	Array of symbols created or managed by this hook
addSymbol	(symbol: symbol) => void	Adds an existing symbol to the managed collection
removeSymbol	(symbol: symbol) => void	Removes a symbol from the managed collection
clearSymbols	() => void	Clears all symbols from the managed collection

Examples

Creating Unique Property Keys

Use symbols as unique property keys that won't collide

const { createSymbol } = useSymbol();

const privateKey = createSymbol('private');
const obj = {
  publicProp: 'visible',
  [privateKey]: 'hidden'
};

// privateKey is unique and won't conflict with other properties

Global Symbol Registry

Share symbols across different parts of your application

const { getGlobalSymbol, getSymbolKey } = useSymbol();

const sharedSymbol = getGlobalSymbol('app.config');
const key = getSymbolKey(sharedSymbol); // 'app.config'

// Same symbol can be retrieved elsewhere with getGlobalSymbol('app.config')

Well-Known Symbols

Access built-in JavaScript symbols for custom behavior

const { wellKnownSymbols } = useSymbol();

const customIterable = {
  [wellKnownSymbols.iterator]: function* () {
    yield 1;
    yield 2;
    yield 3;
  }
};

// Now customIterable can be used with for...of loops

Symbol Management

Track and manage symbols in your component

const { symbols, createSymbol, removeSymbol, clearSymbols } = useSymbol();

const handleCreateKey = () => {
  const newKey = createSymbol('dynamic-key');
  console.log(`Created symbol, total: ${symbols.length}`);
};

const handleClear = () => {
  clearSymbols();
  console.log('All symbols cleared');
};

Type Checking and Utilities

Utility functions for working with symbols

const { isSymbol, getDescription, createSymbol } = useSymbol();

const mySymbol = createSymbol('test symbol');

if (isSymbol(mySymbol)) {
  const desc = getDescription(mySymbol); // 'test symbol'
  console.log(`Symbol description: ${desc}`);
}

Dependencies

react

Notes

•Symbols created with createSymbol() are guaranteed to be unique
•Global symbols created with getGlobalSymbol() can be shared across the application
•Well-known symbols enable customization of built-in JavaScript operations
•The hook maintains a collection of symbols for easy management and cleanup
•Symbols are garbage collectable and can be used as WeakMap keys
•Each Symbol() call creates a completely unique value, even with the same description

Implementation

"use client";

import { useState, useCallback, useMemo, useRef } from "react";

interface UseSymbolReturn {
  // Create new unique symbols
  createSymbol: (description?: string) => symbol;

  // Global symbol registry operations
  getGlobalSymbol: (key: string) => symbol;
  getSymbolKey: (symbol: symbol) => string | undefined;

  // Symbol utilities
  isSymbol: (value: any) => value is symbol;
  getDescription: (symbol: symbol) => string | undefined;

  // Well-known symbols
  wellKnownSymbols: {
    iterator: symbol;
    asyncIterator: symbol;
    hasInstance: symbol;
    isConcatSpreadable: symbol;
    species: symbol;
    toPrimitive: symbol;
    toStringTag: symbol;
    unscopables: symbol;
    match: symbol;
    matchAll: symbol;
    replace: symbol;
    search: symbol;
    split: symbol;
  };

  // Symbol collection management
  symbols: symbol[];
  addSymbol: (symbol: symbol) => void;
  removeSymbol: (symbol: symbol) => void;
  clearSymbols: () => void;
}

export function useSymbol(): UseSymbolReturn {
  const [symbols, setSymbols] = useState<symbol[]>([]);
  const symbolsRef = useRef<Set<symbol>>(new Set());

  const createSymbol = useCallback((description?: string): symbol => {
    const newSymbol = Symbol(description);
    setSymbols((prev) => [...prev, newSymbol]);
    symbolsRef.current.add(newSymbol);
    return newSymbol;
  }, []);

  const getGlobalSymbol = useCallback((key: string): symbol => {
    return Symbol.for(key);
  }, []);

  const getSymbolKey = useCallback((symbol: symbol): string | undefined => {
    return Symbol.keyFor(symbol);
  }, []);

  const isSymbol = useCallback((value: any): value is symbol => {
    return typeof value === "symbol";
  }, []);

  const getDescription = useCallback((symbol: symbol): string | undefined => {
    return symbol.description;
  }, []);

  const addSymbol = useCallback((symbol: symbol) => {
    if (!symbolsRef.current.has(symbol)) {
      setSymbols((prev) => [...prev, symbol]);
      symbolsRef.current.add(symbol);
    }
  }, []);

  const removeSymbol = useCallback((symbol: symbol) => {
    if (symbolsRef.current.has(symbol)) {
      setSymbols((prev) => prev.filter((s) => s !== symbol));
      symbolsRef.current.delete(symbol);
    }
  }, []);

  const clearSymbols = useCallback(() => {
    setSymbols([]);
    symbolsRef.current.clear();
  }, []);

  const wellKnownSymbols = useMemo(
    () => ({
      iterator: Symbol.iterator,
      asyncIterator: Symbol.asyncIterator,
      hasInstance: Symbol.hasInstance,
      isConcatSpreadable: Symbol.isConcatSpreadable,
      species: Symbol.species,
      toPrimitive: Symbol.toPrimitive,
      toStringTag: Symbol.toStringTag,
      unscopables: Symbol.unscopables,
      match: Symbol.match,
      matchAll: Symbol.matchAll,
      replace: Symbol.replace,
      search: Symbol.search,
      split: Symbol.split,
    }),
    []
  );

  return {
    createSymbol,
    getGlobalSymbol,
    getSymbolKey,
    isSymbol,
    getDescription,
    wellKnownSymbols,
    symbols,
    addSymbol,
    removeSymbol,
    clearSymbols,
  };
}

usePrevious

CLI Docs All Hooks

useThrottle