ARIA in React: Stop Using aria-label Wrong

The Rules You Need to Know First

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);
}