React useId Hook Guide

The useId hook generates unique IDs that are stable across server and client rendering. Here's how to use it.

Basic Usage#

import { useId } from 'react';

function EmailInput() {
  const id = useId();

  return (
    <div>
      <label htmlFor={id}>Email</label>
      <input id={id} type="email" />
    </div>
  );
}

// Each instance gets unique ID
function App() {
  return (
    <>
      <EmailInput /> {/* id=":r0:" */}
      <EmailInput /> {/* id=":r1:" */}
      <EmailInput /> {/* id=":r2:" */}
    </>
  );
}

Multiple IDs per Component#

function LoginForm() {
  const id = useId();

  return (
    <form>
      <div>
        <label htmlFor={`${id}-email`}>Email</label>
        <input id={`${id}-email`} type="email" />
      </div>

      <div>
        <label htmlFor={`${id}-password`}>Password</label>
        <input id={`${id}-password`} type="password" />
      </div>

      <div>
        <input
          id={`${id}-remember`}
          type="checkbox"
        />
        <label htmlFor={`${id}-remember`}>Remember me</label>
      </div>
    </form>
  );
}

Accessibility Attributes#

// aria-describedby
function PasswordInput() {
  const id = useId();
  const hintId = `${id}-hint`;
  const errorId = `${id}-error`;

  return (
    <div>
      <label htmlFor={id}>Password</label>
      <input
        id={id}
        type="password"
        aria-describedby={`${hintId} ${errorId}`}
      />
      <p id={hintId}>Must be at least 8 characters</p>
      <p id={errorId} role="alert">Password is required</p>
    </div>
  );
}

// aria-labelledby
function Card({ title, children }) {
  const titleId = useId();

  return (
    <article aria-labelledby={titleId}>
      <h2 id={titleId}>{title}</h2>
      {children}
    </article>
  );
}

// aria-controls
function Accordion({ title, children }) {
  const id = useId();
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button
        aria-expanded={isOpen}
        aria-controls={id}
        onClick={() => setIsOpen(!isOpen)}
      >
        {title}
      </button>
      <div id={id} hidden={!isOpen}>
        {children}
      </div>
    </div>
  );
}

Form Field Component#

interface FormFieldProps {
  label: string;
  type?: string;
  error?: string;
  hint?: string;
  required?: boolean;
}

function FormField({
  label,
  type = 'text',
  error,
  hint,
  required,
}: FormFieldProps) {
  const id = useId();
  const hintId = hint ? `${id}-hint` : undefined;
  const errorId = error ? `${id}-error` : undefined;

  const describedBy = [hintId, errorId].filter(Boolean).join(' ') || undefined;

  return (
    <div className="form-field">
      <label htmlFor={id}>
        {label}
        {required && <span aria-hidden="true">*</span>}
      </label>

      <input
        id={id}
        type={type}
        aria-describedby={describedBy}
        aria-invalid={!!error}
        aria-required={required}
      />

      {hint && (
        <p id={hintId} className="hint">
          {hint}
        </p>
      )}

      {error && (
        <p id={errorId} className="error" role="alert">
          {error}
        </p>
      )}
    </div>
  );
}

// Usage
<FormField
  label="Username"
  required
  hint="3-20 characters"
  error={errors.username}
/>

function Tooltip({ content, children }) {
  const id = useId();
  const [isVisible, setIsVisible] = useState(false);

  return (
    <span className="tooltip-wrapper">
      <span
        aria-describedby={isVisible ? id : undefined}
        onMouseEnter={() => setIsVisible(true)}
        onMouseLeave={() => setIsVisible(false)}
        onFocus={() => setIsVisible(true)}
        onBlur={() => setIsVisible(false)}
      >
        {children}
      </span>

      {isVisible && (
        <span id={id} role="tooltip" className="tooltip">
          {content}
        </span>
      )}
    </span>
  );
}

// Usage
<Tooltip content="Click to submit the form">
  <button>Submit</button>
</Tooltip>

function Modal({ isOpen, onClose, title, children }) {
  const titleId = useId();
  const descriptionId = useId();

  if (!isOpen) return null;

  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby={titleId}
      aria-describedby={descriptionId}
    >
      <h2 id={titleId}>{title}</h2>
      <div id={descriptionId}>{children}</div>
      <button onClick={onClose}>Close</button>
    </div>
  );
}

// Usage
<Modal
  isOpen={showModal}
  onClose={() => setShowModal(false)}
  title="Confirm Action"
>
  <p>Are you sure you want to proceed?</p>
</Modal>

Tab Panel#

function Tabs({ tabs }) {
  const id = useId();
  const [activeIndex, setActiveIndex] = useState(0);

  return (
    <div>
      <div role="tablist">
        {tabs.map((tab, index) => (
          <button
            key={index}
            role="tab"
            id={`${id}-tab-${index}`}
            aria-controls={`${id}-panel-${index}`}
            aria-selected={activeIndex === index}
            onClick={() => setActiveIndex(index)}
          >
            {tab.label}
          </button>
        ))}
      </div>

      {tabs.map((tab, index) => (
        <div
          key={index}
          role="tabpanel"
          id={`${id}-panel-${index}`}
          aria-labelledby={`${id}-tab-${index}`}
          hidden={activeIndex !== index}
        >
          {tab.content}
        </div>
      ))}
    </div>
  );
}

// Usage
<Tabs
  tabs={[
    { label: 'Profile', content: <ProfilePanel /> },
    { label: 'Settings', content: <SettingsPanel /> },
    { label: 'Notifications', content: <NotificationsPanel /> },
  ]}
/>

Radio Group#

function RadioGroup({ name, options, value, onChange }) {
  const groupId = useId();

  return (
    <div role="radiogroup" aria-labelledby={`${groupId}-label`}>
      <span id={`${groupId}-label`} className="label">
        {name}
      </span>

      {options.map((option, index) => {
        const optionId = `${groupId}-option-${index}`;

        return (
          <div key={option.value}>
            <input
              type="radio"
              id={optionId}
              name={name}
              value={option.value}
              checked={value === option.value}
              onChange={() => onChange(option.value)}
            />
            <label htmlFor={optionId}>{option.label}</label>
          </div>
        );
      })}
    </div>
  );
}

// Usage
<RadioGroup
  name="Size"
  options={[
    { label: 'Small', value: 'sm' },
    { label: 'Medium', value: 'md' },
    { label: 'Large', value: 'lg' },
  ]}
  value={size}
  onChange={setSize}
/>

Custom Hook with useId#

// useFormField hook
function useFormField(label: string) {
  const id = useId();

  return {
    labelProps: {
      htmlFor: id,
      children: label,
    },
    inputProps: {
      id,
      'aria-label': label,
    },
  };
}

// Usage
function Input({ label }) {
  const { labelProps, inputProps } = useFormField(label);

  return (
    <div>
      <label {...labelProps} />
      <input {...inputProps} />
    </div>
  );
}

// useDisclosure hook
function useDisclosure() {
  const id = useId();
  const [isOpen, setIsOpen] = useState(false);

  return {
    isOpen,
    open: () => setIsOpen(true),
    close: () => setIsOpen(false),
    toggle: () => setIsOpen((prev) => !prev),
    triggerProps: {
      'aria-expanded': isOpen,
      'aria-controls': id,
      onClick: () => setIsOpen((prev) => !prev),
    },
    contentProps: {
      id,
      hidden: !isOpen,
    },
  };
}

Best Practices#

Usage:
✓ Use for accessibility attributes
✓ Use for form label/input pairing
✓ Use for ARIA relationships
✓ Prefix for multiple IDs

Benefits:
✓ Stable across server/client
✓ Unique per component instance
✓ No ID collisions
✓ Works with SSR

Patterns:
✓ Create base ID, derive others
✓ Use in reusable components
✓ Combine with custom hooks
✓ Always pair labels with inputs

Avoid:
✗ Using for CSS selectors
✗ Using for keys in lists
✗ Relying on specific format
✗ Using outside React components

The useId hook generates stable, unique IDs for accessibility attributes and form elements. Use it to properly associate labels with inputs, connect ARIA attributes, and build accessible reusable components. It ensures IDs match between server and client rendering.