Concepts

React Aria is built around three core principles: Accessibility, Internationalization, and Interactions. Together, these ensure that every component you build works for everyone, everywhere, and on every device.

Accessibility

Accessible applications are usable by everyone, including people with disabilities. Accessibility benefits all users — not just those using assistive technologies — by improving efficiency, consistency, and usability.

React Aria provides built-in support for screen readers and keyboard navigation, following the WAI-ARIA and ARIA Authoring Practices guidelines. It supplies the correct semantics via ARIA roles and attributes, handles keyboard and pointer events, manages focus, and provides screen reader announcements. React Aria components are tested across a wide variety of devices, browsers, and screen readers.

You’re responsible for providing meaningful labels and ensuring your visual design supports all users. This includes designing with sufficient color contrast and hit target sizes, including visible focus rings, respecting motion preferences, and more. The WCAG guidelines are a good resource to reference when designing and building components with React Aria.

Labeling

Most components should have a visible label, which is usually provided by rendering a <Label> element within it. This is associated with the component automatically.

import {TextField, Label, Input} from 'react-aria-components';

<TextField>
  <Label>First name</Label>
  <Input />
</TextField>

When a component doesn't have a visible label, it must have an aria-label or aria-labelledby prop to provide an accessible name.

import {ProgressBar} from 'react-aria-components';

<ProgressBar
  aria-label="Processing" />

Supported screen readers

React Aria is tested across a variety of devices, browsers, and screen readers.

VoiceOver on macOS in Safari and Chrome
JAWS on Windows in Firefox and Chrome
NVDA on Windows in Firefox and Chrome
VoiceOver on iOS
TalkBack on Android in Chrome

Automated testing

Automated accessibility testing tools sometimes catch false positives in React Aria. These are documented in our wiki. Use the rules below to ignore these issues in your own testing tools, such as in the Storybook test runner or Storybook a11y addon.

{
  rules: [
    {
      id: 'aria-hidden-focus',
      selector: 'body *:not([data-a11y-ignore="aria-hidden-focus"])'
    }
  ]
}

Internationalization

Localization is an important way to make your application usable by the widest number of people. React Aria includes localized strings for 30+ languages, handles dates and numbers in many calendar and numbering systems, and supports right-to-left interactions (e.g. keyboard navigation).

You’re responsible for ensuring your design supports right-to-left layout, and adapts to different languages (e.g. using appropriate fonts). Modern CSS grid and flex layouts are automatically mirrored depending on the direction, and logical properties can be used to adapt margins, paddings, borders, etc.

Setting the locale

React Aria automatically detects the user's current language by default. Use the I18nProvider component to set the locale to a specific value. You should also set the lang and dir attributes on the root-most element of your application.

import {I18nProvider, useLocale} from 'react-aria-components';

<I18nProvider locale="fr-FR">
  <App />
</I18nProvider>

function App() {
  let {locale, direction} = useLocale();

  return (
    <html lang={locale} dir={direction}>
      {/* your app here */}
    </html>
  );
}

Supported locales

Arabic (United Arab Emirates)
Bulgarian (Bulgaria)
Chinese (Simplified)
Chinese (Traditional)
Croatian (Croatia)
Czech (Czech Republic)
Danish (Denmark)
Dutch (Netherlands)
English (Great Britain)
English (United States)
Estonian (Estonia)
Finnish (Finland)
French (Canada)
French (France)
German (Germany)
Greek (Greece)
Hebrew (Israel)
Hungarian (Hungary)
Italian (Italy)
Japanese (Japan)
Korean (Korea)
Latvian (Latvia)
Lithuanian (Lithuania)
Norwegian (Norway)
Polish (Poland)
Portuguese (Brazil)
Romanian (Romania)
Russian (Russia)
Serbian (Serbia)
Slovakian (Slovakia)
Slovenian (Slovenia)
Spanish (Spain)
Swedish (Sweden)
Turkish (Turkey)
Ukrainian (Ukraine)

Interactions

Modern web apps run on everything from desktops to mobile devices to TVs, with users interacting through mouse, touch, keyboard, and assistive technologies. React Aria normalizes these differences, delivering consistent “press”, “hover”, and “focus” behaviors across all browsers and input types.

React Aria components provide data attributes and render props to style these states:

data-pressed – like the :active pseudo class, but removed when dragging off the element.
data-hovered – like :hover, but does not apply on touch devices to avoid sticky hover states.
data-focus-visible – like :focus-visible, but avoids false positives from programmatic focus.

These states also come with corresponding events such as onPress and onHoverStart. To use these events in your own custom components, see hooks such as usePress, useHover, useMove, and useFocusRing.

Read our blog post series to learn more about the intricacies behind these interactions.

Higher level interaction patterns such as selection and drag and drop are also built on top of these low level primitives.