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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Button
✓ import { Button } from 'react-aria-components'
✗ const { Button } = require('react-aria-components')
React Aria Components is primarily designed for ES Modules (ESM). Using CommonJS `require` syntax might lead to issues in certain bundler configurations or fail in environments that enforce ESM. Always prefer named ESM imports.
TextField
✓ import { TextField, Label, Input } from 'react-aria-components'
✗ import TextField from 'react-aria-components'
Many RAC components, like `TextField`, are composite and require specific sub-components (e.g., `Label`, `Input`) to be imported and composed as children for correct structure and accessibility. They are typically named exports, not default exports.
Table
✓ import { Table, TableHeader, Column, TableBody, Row, Cell } from 'react-aria-components'
Complex components such as `Table` are built from multiple interconnected components that define its structure and behavior. All necessary sub-components, like `TableHeader`, `Column`, `TableBody`, `Row`, and `Cell`, must be explicitly imported and used according to the documentation for full functionality and ARIA compliance.
This quickstart demonstrates the composition of a simple accessible form using `TextField` (with `Label` and `Input`), a `Button`, and an accessible modal dialog (`DialogTrigger`, `Modal`, `Dialog`) for submission confirmation. It highlights the headless nature of RAC by applying basic Tailwind-like class names for visual styling.
import { Button, Dialog, DialogTrigger, Heading, Modal, Text, TextField, Label, Input } from 'react-aria-components';
import React from 'react';
function MyForm() {
return (
<form className="flex flex-col gap-4 p-4 border border-gray-200 rounded-lg shadow-md max-w-sm mx-auto my-8">
<Heading level={2} className="text-2xl font-semibold text-gray-800">Contact Us</Heading>
<TextField className="flex flex-col gap-1">
<Label className="font-medium text-gray-700">Your Name</Label>
<Input type="text" placeholder="John Doe" className="border border-gray-300 rounded-md p-2 focus:ring-2 focus:ring-blue-400 focus:border-transparent transition-colors duration-150" />
</TextField>
<TextField className="flex flex-col gap-1">
<Label className="font-medium text-gray-700">Email Address</Label>
<Input type="email" placeholder="john.doe@example.com" className="border border-gray-300 rounded-md p-2 focus:ring-2 focus:ring-blue-400 focus:border-transparent transition-colors duration-150" />
</TextField>
<DialogTrigger>
<Button className="bg-blue-600 text-white font-medium py-2 px-4 rounded-md hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-400 focus:ring-offset-2 transition-colors duration-150">
Submit Form
</Button>
<Modal className="fixed inset-0 z-50 flex items-center justify-center bg-black bg-opacity-50 backdrop-blur-sm">
<Dialog className="bg-white p-6 rounded-lg shadow-xl max-w-sm w-full animate-fade-in">
{({ close }) => (
<>
<Heading slot="title" className="text-xl font-bold mb-4">Form Submitted Successfully!</Heading>
<Text className="text-gray-700 mb-6">Thank you for contacting us. We will get back to you shortly.</Text>
<Button
onPress={close}
className="w-full bg-gray-200 text-gray-800 font-medium py-2 px-4 rounded-md hover:bg-gray-300 focus:outline-none focus:ring-2 focus:ring-gray-400 focus:ring-offset-2 transition-colors duration-150"
>
Close
</Button>
</>
)}
</Dialog>
</Modal>
</DialogTrigger>
</form>
);
}
export default MyForm;
Debug
Known issues
gotchaReact Aria Components are entirely unstyled by design. Developers must provide their own CSS or styling solution (e.g., Tailwind CSS, Emotion, Styled Components) to give components any visual appearance. Failure to apply styles will result in invisible or poorly rendered components that only handle accessibility and interaction logic.fixIntegrate a styling framework or write custom CSS. Apply `className` props with utility classes, or use `style` props, to visually define components.
affects: >=1.0.0
gotchaMany React Aria Components are composite, requiring specific sub-components (e.g., `TextField` needs `Label` and `Input`) to be rendered as children. Incorrect composition or missing required children can break ARIA attribute relationships, keyboard navigation, and lead to runtime errors or accessibility violations.fixAlways refer to the official React Aria Components documentation for the correct component structure and composition guidelines. Ensure all required sub-components are correctly imported and nested.
affects: >=1.0.0
gotchaThe library has strict peer dependency requirements for `react` and `react-dom` (currently `^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1`). Using unsupported or incompatible React versions can lead to runtime errors, unexpected behavior, or subtle breakage due to reliance on specific React hook behaviors.fixEnsure your project's `react` and `react-dom` versions are within the supported range. Use `npm install react react-dom` or `yarn add react react-dom` to update your dependencies.
affects: <16.8.0 or outside specified ranges
breakingUsers migrating from directly using React Aria hooks (e.g., `useButton`, `useTextField`) to `react-aria-components` will need to refactor their JSX. `react-aria-components` abstracts the hooks into pre-composed component primitives, meaning you'll replace manual hook integration with declarative component usage. This is a significant architectural shift, though not an API break within RAC itself.fixReplace JSX elements that directly consume `react-aria` hooks and spread their props onto DOM elements with the corresponding `react-aria-components` primitives (e.g., `<Button>` instead of applying `useButton` results to a `button` element).
affects: N/A (affects migration from `react-aria` hooks)
Errors
Common errors & fixes
TypeError: (0 , react_aria_components__WEBPACK_IMPORTED_MODULE_2__.Button) is not a function
Attempting to use CommonJS `require` syntax in a modern build setup, or incorrectly assuming a default export when components are named exports.
fixEnsure you are using named ES module imports: `import { Button } from 'react-aria-components'`. Error: A `TextField` must contain an `Input` and a `Label`.
A composite component was rendered without its essential child components, violating its required structure for accessibility and functionality.
fixAdd all necessary sub-components as children. For `TextField`, ensure `<Label>` and `<Input>` are present within the `<TextField>` component.
Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate.
This often occurs when an event handler (e.g., `onPress`) is passed the *result* of a function call rather than a function reference, causing an infinite loop of re-renders.
fixEnsure event handlers receive a function reference, e.g., `onPress={() => doSomething()}` or `onPress={doSomething}` (if `doSomething` is already a function), instead of `onPress={doSomething()}`. Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined.
This error typically indicates an incorrect import, where the imported symbol is `undefined`. This can happen with typos in named imports or trying to import a non-existent default export.
fixVerify the exact name of the component and ensure it's a named import: `import { CorrectComponentName } from 'react-aria-components'`. Audit
Dependencies
reactrequiredCore React library for UI rendering and component lifecycle management. Required peer dependency.
react-domrequiredProvides DOM-specific rendering methods for React applications. Required peer dependency.