react-aria

library3.48.0jsnpmunverified

React Aria is a collection of unstyled, accessible UI primitives and hooks for building robust and inclusive user interfaces in React. Unlike traditional component libraries that provide pre-styled components, React Aria offers a foundational layer of accessibility, interaction logic, and internationalization, allowing developers complete control over visual styling and DOM structure. The current stable version is 3.48.0, with new features and improvements released frequently, typically on a monthly or bi-monthly cadence. Its core differentiator lies in its 'headless' nature, focusing purely on standardized, accessible behavior by leveraging WAI-ARIA practices, making it an ideal choice for design systems that require highly customizable yet fully accessible components without opinionated styling.

web-framework

npm install react-aria

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-ARIA

react-aria

web-frameworkjavascriptv3.48.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useButton

✓ import { useButton } from 'react-aria';

✗ const { useButton } = require('react-aria');

React Aria is an ESM-first library. CommonJS `require` is generally not recommended and might not work in all environments, especially with modern build tools. Ensure your project is configured for ESM.

useFocusRing

✓ import { useFocusRing } from 'react-aria';

✗ import useFocusRing from 'react-aria/useFocusRing';

All hooks and utilities are typically imported directly from the 'react-aria' package. Direct deep imports from sub-paths are generally not supported or recommended and can lead to issues with tree-shaking or module resolution.

mergeProps

✓ import { mergeProps } from 'react-aria';

Used to safely merge props objects from multiple hooks or custom props without overwriting event handlers or attributes. Essential when combining multiple React Aria hooks or integrating with other libraries.

This quickstart demonstrates how to create a custom accessible button using `useButton` from React Aria, applying the necessary props and a ref to a native HTML button element. It also shows `mergeProps` for combining properties.

import React from 'react'; import { useButton } from 'react-aria'; import { mergeProps } from 'react-aria'; interface MyButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> { onPress?: () => void; } function MyButton(props: MyButtonProps) { let ref = React.useRef<HTMLButtonElement>(null); let { buttonProps, isPressed } = useButton(props, ref); return ( <button {...mergeProps(buttonProps, props)} ref={ref} style={{ backgroundColor: isPressed ? 'darkblue' : 'blue', color: 'white', padding: '10px 20px', border: 'none', borderRadius: '5px', cursor: 'pointer' }} > {props.children} </button> ); } // Example usage in a component export function App() { const handlePress = () => { console.log('Button pressed!'); alert('Hello from React Aria Button!'); }; return ( <div> <h1>React Aria Quickstart</h1> <MyButton onPress={handlePress}>Click Me</MyButton> </div> ); }

Debug

Known issues

gotchaReact Aria provides 'headless' hooks for accessibility and interaction logic, not pre-styled visual components. Developers are responsible for providing all visual styling and the underlying DOM structure. This can be a significant mental model shift for those accustomed to traditional component libraries.

fix

Always remember to spread the returned props from React Aria hooks onto your DOM elements (e.g., `<button {...buttonProps} />`) and to provide a `ref` if the hook requires one.

affects: >=1.0.0

breakingWhile `react-aria` itself focuses on primitives, the introduction and evolution of `@adobe/react-spectrum` and `react-aria-components` represents different architectural approaches to building UI. Users of `@adobe/react-spectrum` (a styled component library) or `react-aria-components` (unstyled components built on `react-aria` hooks) should be aware that their APIs and usage patterns differ significantly from directly using `react-aria` hooks.

fix

Determine whether you need 'headless' hooks (react-aria), 'unstyled components' (react-aria-components), or 'styled components' (react-spectrum) for your project and use the appropriate package and documentation. Do not mix and match without understanding the implications.

affects: >=3.0.0

gotchaThe peer dependencies for `react` and `react-dom` include a wide range of versions (e.g., `^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1`). While this offers flexibility, ensure your project's React version aligns with the tested ranges to avoid potential compatibility issues, especially with pre-release versions.

fix

Verify your `react` and `react-dom` versions in `package.json` are within the supported peer dependency range for the `react-aria` version you are using. Update React if necessary, or consider a different `react-aria` version if constraints are an issue.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of null (reading 'focus')

This error often occurs when a `ref` required by a React Aria hook is not properly assigned to the corresponding DOM element, or the element is not mounted when the hook tries to interact with it.

fix

Ensure the `ref` returned by `React.useRef()` is passed to the DOM element (`ref={myRef}`) that the React Aria hook expects to control or observe. Check for conditional rendering that might cause the element to be null when the hook executes.

Accessibility warning: 'Some element' must have a label accessible to screen readers, or you must provide an `aria-label` or `aria-labelledby` prop.

React Aria ensures proper WAI-ARIA roles and attributes, but it relies on the developer to provide semantic content and labels where appropriate. This warning indicates a missing accessible name.

fix

Provide a visible label as children to the component, or explicitly add an `aria-label` or `aria-labelledby` prop to the element. For example, a button created with `useButton` needs text content or an `aria-label`.

Upgrade

Version history

3.48.0latest on npm

Audit

Dependencies

reactrequiredRequired as a peer dependency for all React-based components and hooks.

react-domrequiredRequired as a peer dependency for DOM rendering and interaction.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/adobe/react-spectrum ↗

packagehttps://www.npmjs.com/package/react-aria ↗

homepagehttps://react-spectrum.adobe.com/react-aria/ ↗