ARIA in React: Stop Using aria-label Wrong

The Rules You Need to Know First

The First Rule of ARIA: Do Not Use ARIA

// ❌ Wrong: a div pretending to be a button
<div role="button" onClick={submit}>Submit</div>

// ⚠️ Better, but you now maintain browser behaviour by hand
<div
  role="button"
  tabIndex={0}
  onClick={submit}
  onKeyDown={(e) => {
    if (e.key === "Enter" || e.key === " ") {
      e.preventDefault();
      submit();
    }
  }}
>
  Submit
</div>

// ✅ Correct: the platform already solved this
<button type="button" onClick={submit}>Submit</button>

How the Accessible Name Is Computed

1. aria-labelledby, resolved by concatenating the text content of every referenced id in the order you list them.
2. aria-label, used only when aria-labelledby is absent or resolves to an empty string.
3. The host language label: <label htmlFor> for form controls, <caption> for tables, <legend> for fieldsets, alt for images.
4. The element's own text content, for roles that allow a name from content such as buttons, links, and headings.
5. The title attribute, a last resort that also produces a mouse tooltip most users never see.
6. placeholder on some inputs, a browser fallback you should never rely on deliberately.

// Announced as "Save draft": aria-labelledby beats everything below it
<button aria-labelledby="save-hint" aria-label="Save" title="Save as draft">
  Submit
</button>
<span id="save-hint">Save draft</span>

// Announced as "Save": aria-label beats the visible text content
<button aria-label="Save">Submit</button>

// Announced as "Submit": no ARIA, so the text content becomes the name
<button>Submit</button>

function EmailField({ error }: { error?: string }) {
  const id = useId();
  const hintId = `${id}-hint`;
  const errorId = `${id}-error`;

  return (
    <div>
      <label htmlFor={id}>Email address</label>
      <input
        id={id}
        type="email"
        // Both ids are read, in the order listed
        aria-describedby={error ? `${hintId} ${errorId}` : hintId}
        aria-invalid={error ? true : undefined}
      />
      <p id={hintId}>We only use this to send receipts.</p>
      {error && <p id={errorId}>{error}</p>}
    </div>
  );
}

The 5 Patterns

1. 1

   Icon Button with No Visible Text

   This is one of the few legitimate uses for aria-label: when there is genuinely no visible text and adding a label isn't feasible. Two details matter: the aria-label on the button and aria-hidden="true" on the icon to prevent the screen reader from also describing the SVG.

   tsxCopy

   // ❌ Wrong: no accessible name, screen reader announces nothing useful
   <button onClick={onClose}>
     <XIcon />
   </button>
   
   // ✅ Correct: aria-label gives it an accessible name
   <button onClick={onClose} aria-label="Close dialog">
     <XIcon aria-hidden="true" />
   </button>

   • aria-hidden="true" on the icon prevents the screen reader from announcing "Close dialog, svg" (redundant once the button has a name)
   • Without aria-hidden on the icon, screen readers may announce both the aria-label and the SVG title
   • If a visible tooltip exists, consider making it the accessible name via aria-labelledby instead
2. 2

   Modal Dialog

   A modal needs three things: role="dialog", a label connecting it to its visible title, and focus management. Most React implementations get one or two and miss the third.

   tsx — ❌ Wrong: missing label and focus managementCopy

   <div className="modal">
     <h2>Confirm Delete</h2>
     <p>Are you sure?</p>
     <button onClick={onClose}>Cancel</button>
   </div>

   tsx — ✅ Correct: role, aria-labelledby, focus managementCopy

   function Modal({ isOpen, title, children, onClose }) {
     const titleId = useId();
     const modalRef = useRef<HTMLDivElement>(null);
   
     useEffect(() => {
       if (isOpen) modalRef.current?.focus();
     }, [isOpen]);
   
     if (!isOpen) return null;
   
     return (
       <div
         role="dialog"
         aria-modal="true"
         aria-labelledby={titleId}  // points to visible title (translation-safe)
         tabIndex={-1}
         ref={modalRef}
       >
         <h2 id={titleId}>{title}</h2>
         {children}
         <button onClick={onClose}>Close</button>
       </div>
     );
   }

   • aria-modal="true" tells screen readers to treat content outside the dialog as inert: without it, some screen readers let users navigate behind the modal
   • tabIndex={-1} allows the div to receive programmatic focus from useEffect without entering the tab order
   • Focus must return to the triggering element when the modal closes: add triggerRef.current?.focus() in the close handler
3. 3

   Toast Notifications with aria-live

   Toast notifications are the most common case where developers forget ARIA entirely, leaving screen reader users unaware a message appeared.

   tsx — ❌ Wrong: dynamically injecting the live regionCopy

   // Injecting a live region at toast time, screen readers won't announce it
   {showToast && (
     <div aria-live="polite">{message}</div>
   )}

   tsx — ✅ Correct: persistent live region, always in the DOMCopy

   function ToastContainer({ message }: { message: string | null }) {
     return (
       // Always rendered: screen readers observe it from page load
       // aria-atomic="true" announces the whole region, not just changed text
       <div
         aria-live="polite"
         aria-atomic="true"
         className="sr-only"
       >
         {message}
       </div>
     );
   }

   • The container must always be in the DOM: screen readers only observe live regions that existed when the page loaded
   • aria-live="polite" waits for current speech to finish: use for success messages and status updates
   • aria-live="assertive" interrupts immediately: reserve for genuine errors requiring immediate attention
4. 4

   Loading Spinner

   A spinning animation with no text tells a screen reader nothing. role="status" is live region shorthand for aria-live="polite".

   tsx — ❌ Wrong: no accessible informationCopy

   <div className="spinner">
     <svg className="animate-spin" />
   </div>

   tsx — ✅ Correct: role, label, hidden iconCopy

   function LoadingSpinner({ label = "Loading..." }: { label?: string }) {
     return (
       <div role="status" aria-label={label}>
         <svg aria-hidden="true" className="animate-spin" />
         <span className="sr-only">{label}</span>
       </div>
     );
   }

   • aria-hidden="true" prevents screen readers from attempting to describe the SVG animation
   • The sr-only span provides a fallback in browsers where live region aria-label support is inconsistent
   • When loading completes, ensure focus or a content update announces the result: the spinner disappearing is not announced
5. 5

   Tab Panel

   Custom tab components are common in React and almost universally implemented without correct ARIA. The aria-controls / aria-labelledby pairing creates a semantic relationship between each tab and its panel.

   tsx — ❌ Wrong: no ARIA roles or relationshipsCopy

   <div className="tabs">
     {tabs.map((tab, i) => (
       <button
         key={tab.id}
         className={activeTab === i ? 'active' : ''}
         onClick={() => setActiveTab(i)}
       >
         {tab.label}
       </button>
     ))}
     <div>{tabs[activeTab].content}</div>
   </div>

   tsx — ✅ Correct: full ARIA tab patternCopy

   function Tabs({ tabs }: { tabs: Tab[] }) {
     const [activeTab, setActiveTab] = useState(0);
   
     return (
       <div>
         <div role="tablist" aria-label="Account settings">
           {tabs.map((tab, i) => (
             <button
               key={tab.id}
               role="tab"
               aria-selected={activeTab === i}   // active state, not aria-pressed
               aria-controls={`panel-${tab.id}`}  // links tab to its panel
               id={`tab-${tab.id}`}
               onClick={() => setActiveTab(i)}
             >
               {tab.label}
             </button>
           ))}
         </div>
   
         {tabs.map((tab, i) => (
           <div
             key={tab.id}
             role="tabpanel"
             id={`panel-${tab.id}`}
             aria-labelledby={`tab-${tab.id}`}
             hidden={activeTab !== i}
           >
             {tab.content}
           </div>
         ))}
       </div>
     );
   }

   • aria-selected communicates the active tab: aria-pressed is wrong here and confuses the tab pattern
   • hidden is preferred over CSS display: none: it removes inactive panels from the accessibility tree entirely
   • Arrow-key navigation between tabs is part of the ARIA pattern: a tab that only responds to click fails keyboard users

Accessibility Shipping Checklist

• Icon-only buttons have aria-label and SVG has aria-hidden="true"
• Modals have role="dialog", aria-modal="true", aria-labelledby pointing to the visible title, and focus management
• Toast/notification container is always in the DOM with aria-live="polite" and aria-atomic="true"
• Loading spinners have role="status" and aria-hidden on the SVG
• Tab components use role="tab", aria-selected, aria-controls, and role="tabpanel" with aria-labelledby
• Ran axe DevTools (zero violations)
• Tested keyboard navigation (every interactive element reachable without a mouse)
• Tested with VoiceOver or NVDA (announcements make sense without visual context)

Testing Tools

if (process.env.NODE_ENV !== 'production') {
  const axe = await import('@axe-core/react');
  const React = await import('react');
  const ReactDOM = await import('react-dom');
  axe.default(React.default, ReactDOM.default, 1000);
}

// Broken: server and client disagree, and the counter resets per bundle
const randomId = `field-${Math.random()}`;
let counter = 0;
const countedId = `field-${counter++}`;

// Correct: stable across server render, hydration, and every instance
const id = useId();
<h2 id={`${id}-title`}>Billing details</h2>
<section aria-labelledby={`${id}-title`}>...</section>

const triggerRef = useRef<HTMLButtonElement>(null);

function closeModal() {
  setOpen(false);
  // Restore after React has committed the removal
  requestAnimationFrame(() => triggerRef.current?.focus());
}

<button ref={triggerRef} onClick={() => setOpen(true)}>Edit profile</button>