react-aria

Spectrum UI components in React

weekly downloads1.8M

versionv3.46.0

licenseApache-2.0

categoryui-library

Overview

react-aria is a library of unstyled React Hooks that implements accessible UI primitives following WAI-ARIA specifications. Unlike traditional component libraries that ship with pre-built styling, react-aria provides the behavior, accessibility, and interaction logic while leaving all visual design decisions to you. It handles complex concerns like keyboard navigation, focus management, screen reader announcements, and cross-browser event normalization through a composable hook-based API.

The library was developed by Adobe as part of their Spectrum design system but is designed to work with any design system or custom component library. With over 1.7 million weekly downloads, it's widely adopted by teams building accessible design systems from scratch. The architecture separates state management (often delegated to react-stately), behavior logic, and rendering into distinct layers, enabling developers to compose exactly the functionality they need without inheriting unnecessary abstractions.

react-aria excels at solving the "accessibility tax" problem—the enormous effort required to make custom components work correctly with assistive technologies, support internationalization, and handle edge cases across devices. Rather than reimplementing complex ARIA patterns for each component, developers can leverage battle-tested hooks that encapsulate years of accessibility expertise. The library supports 30+ languages with RTL support, localized formatting, and adaptive interactions that work consistently across mouse, touch, keyboard, and screen reader inputs.

The target audience includes teams building custom design systems, component library authors who need accessibility without design constraints, and developers who want more control than pre-styled libraries offer. It's particularly valuable when you need to match specific brand guidelines, integrate with existing CSS methodologies, or support multiple platforms using shared state logic.

Quick Start

typescript

import { useButton } from '@react-aria/button';
import { useToggleState } from '@react-stately/toggle';
import { useSwitch } from '@react-aria/switch';
import { useRef } from 'react';

function AccessibleSwitch({ children, defaultSelected, onChange }) {
  const state = useToggleState({ defaultSelected, onChange });
  const ref = useRef(null);
  const { inputProps } = useSwitch({ children }, state, ref);

  return (
    <label style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
      <input
        {...inputProps}
        ref={ref}
        style={{ width: '40px', height: '20px' }}
      />
      {children}
    </label>
  );
}

function MenuButtonExample() {
  const ref = useRef(null);
  const { buttonProps } = useButton(
    {
      onPress: () => console.log('Accessible button pressed'),
      elementType: 'button'
    },
    ref
  );

  return (
    <button
      {...buttonProps}
      ref={ref}
      style={{
        padding: '10px 20px',
        background: '#0078d4',
        color: 'white',
        border: 'none',
        borderRadius: '4px',
        cursor: 'pointer'
      }}
    >
      Accessible Button
    </button>
  );
}

export default function App() {
  return (
    <div>
      <MenuButtonExample />
      <AccessibleSwitch
        defaultSelected={false}
        onChange={(isSelected) => console.log('Switch:', isSelected)}
      >
        Enable notifications
      </AccessibleSwitch>
    </div>
  );
}

Use Cases

Building custom design system components: Teams creating their own component libraries can use react-aria hooks to handle all accessibility concerns while implementing their unique visual design. For example, building a combobox with custom filtering logic and brand-specific styling while ensuring full keyboard navigation and screen reader support.

Migrating from inaccessible custom components: Existing applications with custom-built dropdowns, modals, or date pickers that lack proper accessibility can incrementally adopt react-aria hooks to add ARIA attributes, focus management, and keyboard interactions without redesigning the component structure.

Cross-platform design systems: Organizations building components for both web and React Native can share state management logic using react-stately (react-aria's companion library) while implementing platform-specific rendering layers, reducing duplication of complex state machines.

Internationalized applications: Products serving global markets can leverage react-aria's built-in i18n support for date pickers, number inputs, and RTL layouts without manually handling locale-specific formatting and text direction changes.

White-label products: SaaS platforms offering customizable UIs to different clients can use react-aria's headless approach to maintain one accessible component core while allowing each client to apply completely different visual themes through their own CSS and markup structure.

Pros & Cons

Pros

+Complete control over DOM structure, styling, and rendering—no CSS specificity battles or style overrides needed
+Production-grade accessibility implementation covering ARIA patterns, keyboard navigation, focus management, and screen reader testing that would take months to build correctly
+Comprehensive internationalization support including 30+ locales, RTL layouts, and localized date/number formatting built into relevant components
+Compositional API allows mixing hooks at different abstraction levels—use high-level hooks for common patterns or low-level primitives for custom behavior
+Well-maintained by Adobe with extensive documentation, real-world testing through Spectrum UI, and active community support

Cons

−Steeper learning curve than component libraries—requires understanding ARIA patterns, proper hook composition, and managing refs correctly
−More boilerplate code compared to pre-built component libraries since you must handle DOM structure, styling, and prop spreading yourself
−API occasionally differs from native HTML patterns (like press events vs click) which can create friction when integrating with other libraries expecting standard DOM events
−No visual appearance out of the box means significant upfront investment before having working UI, making prototyping slower than styled libraries
−Documentation primarily focuses on individual hooks—finding the right combination for complex patterns sometimes requires reading multiple pages and examples

Alternatives

downshiftv9.3.2

🏎 A set of primitives to build simple, flexible, WAI-ARIA compliant React autocomplete, combobox or select dropdown components.

frontendenhanced inputreact

2.6M / week

@headlessui/reactv2.2.9

A set of completely unstyled, fully accessible UI components for React, designed to integrate beautifully with Tailwind CSS.

ui-library

4.0M / week

Install

bash

npm install react-aria

bash

pnpm add react-aria

bash

bun add react-aria

Overview

Quick Start

typescript

import { useButton } from '@react-aria/button';
import { useToggleState } from '@react-stately/toggle';
import { useSwitch } from '@react-aria/switch';
import { useRef } from 'react';

function AccessibleSwitch({ children, defaultSelected, onChange }) {
  const state = useToggleState({ defaultSelected, onChange });
  const ref = useRef(null);
  const { inputProps } = useSwitch({ children }, state, ref);

  return (
    <label style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
      <input
        {...inputProps}
        ref={ref}
        style={{ width: '40px', height: '20px' }}
      />
      {children}
    </label>
  );
}

function MenuButtonExample() {
  const ref = useRef(null);
  const { buttonProps } = useButton(
    {
      onPress: () => console.log('Accessible button pressed'),
      elementType: 'button'
    },
    ref
  );

  return (
    <button
      {...buttonProps}
      ref={ref}
      style={{
        padding: '10px 20px',
        background: '#0078d4',
        color: 'white',
        border: 'none',
        borderRadius: '4px',
        cursor: 'pointer'
      }}
    >
      Accessible Button
    </button>
  );
}

export default function App() {
  return (
    <div>
      <MenuButtonExample />
      <AccessibleSwitch
        defaultSelected={false}
        onChange={(isSelected) => console.log('Switch:', isSelected)}
      >
        Enable notifications
      </AccessibleSwitch>
    </div>
  );
}

Use Cases

Pros & Cons

Pros

+Complete control over DOM structure, styling, and rendering—no CSS specificity battles or style overrides needed
+Production-grade accessibility implementation covering ARIA patterns, keyboard navigation, focus management, and screen reader testing that would take months to build correctly
+Comprehensive internationalization support including 30+ locales, RTL layouts, and localized date/number formatting built into relevant components
+Compositional API allows mixing hooks at different abstraction levels—use high-level hooks for common patterns or low-level primitives for custom behavior
+Well-maintained by Adobe with extensive documentation, real-world testing through Spectrum UI, and active community support

Cons

−Steeper learning curve than component libraries—requires understanding ARIA patterns, proper hook composition, and managing refs correctly
−More boilerplate code compared to pre-built component libraries since you must handle DOM structure, styling, and prop spreading yourself
−API occasionally differs from native HTML patterns (like press events vs click) which can create friction when integrating with other libraries expecting standard DOM events
−No visual appearance out of the box means significant upfront investment before having working UI, making prototyping slower than styled libraries
−Documentation primarily focuses on individual hooks—finding the right combination for complex patterns sometimes requires reading multiple pages and examples