{"id":11649,"library":"react-aria-components","title":"React Aria Components","description":"React Aria Components (RAC) provides a comprehensive set of headless, accessible, and styleable UI components built directly on the highly acclaimed React Aria hooks library. It simplifies the creation of rich user interfaces by offering ready-to-use component primitives for common UI patterns like buttons, text fields, tables, combo boxes, and trees, while leaving the visual styling entirely up to the developer. The library is currently on version 1.17.0 and maintains a frequent release cadence, typically monthly or bi-monthly, introducing new features, improvements, and accessibility enhancements. Its core differentiators are its strong emphasis on WAI-ARIA authoring practices, full type safety with TypeScript, and its 'bring your own styling' approach, making it highly adaptable to any design system. This allows developers to build custom-styled components without compromising on accessibility or complex interaction logic, fostering a robust foundation for building inclusive web applications.","status":"active","version":"1.17.0","language":"javascript","source_language":"en","source_url":"https://github.com/adobe/react-spectrum","tags":["javascript","typescript"],"install":[{"cmd":"npm install react-aria-components","lang":"bash","label":"npm"},{"cmd":"yarn add react-aria-components","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-aria-components","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core React library for UI rendering and component lifecycle management. Required peer dependency.","package":"react","optional":false},{"reason":"Provides DOM-specific rendering methods for React applications. Required peer dependency.","package":"react-dom","optional":false}],"imports":[{"note":"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.","wrong":"const { Button } = require('react-aria-components')","symbol":"Button","correct":"import { Button } from 'react-aria-components'"},{"note":"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.","wrong":"import TextField from 'react-aria-components'","symbol":"TextField","correct":"import { TextField, Label, Input } from 'react-aria-components'"},{"note":"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.","symbol":"Table","correct":"import { Table, TableHeader, Column, TableBody, Row, Cell } from 'react-aria-components'"}],"quickstart":{"code":"import { Button, Dialog, DialogTrigger, Heading, Modal, Text, TextField, Label, Input } from 'react-aria-components';\nimport React from 'react';\n\nfunction MyForm() {\n  return (\n    <form className=\"flex flex-col gap-4 p-4 border border-gray-200 rounded-lg shadow-md max-w-sm mx-auto my-8\">\n      <Heading level={2} className=\"text-2xl font-semibold text-gray-800\">Contact Us</Heading>\n      <TextField className=\"flex flex-col gap-1\">\n        <Label className=\"font-medium text-gray-700\">Your Name</Label>\n        <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\" />\n      </TextField>\n      <TextField className=\"flex flex-col gap-1\">\n        <Label className=\"font-medium text-gray-700\">Email Address</Label>\n        <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\" />\n      </TextField>\n      <DialogTrigger>\n        <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\">\n          Submit Form\n        </Button>\n        <Modal className=\"fixed inset-0 z-50 flex items-center justify-center bg-black bg-opacity-50 backdrop-blur-sm\">\n          <Dialog className=\"bg-white p-6 rounded-lg shadow-xl max-w-sm w-full animate-fade-in\">\n            {({ close }) => (\n              <>\n                <Heading slot=\"title\" className=\"text-xl font-bold mb-4\">Form Submitted Successfully!</Heading>\n                <Text className=\"text-gray-700 mb-6\">Thank you for contacting us. We will get back to you shortly.</Text>\n                <Button\n                  onPress={close}\n                  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\"\n                >\n                  Close\n                </Button>\n              </>\n            )}\n          </Dialog>\n        </Modal>\n      </DialogTrigger>\n    </form>\n  );\n}\n\nexport default MyForm;","lang":"typescript","description":"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."},"warnings":[{"fix":"Integrate a styling framework or write custom CSS. Apply `className` props with utility classes, or use `style` props, to visually define components.","message":"React 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always 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.","message":"Many 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure 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.","message":"The 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.","severity":"gotcha","affected_versions":"<16.8.0 or outside specified ranges"},{"fix":"Replace 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).","message":"Users 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.","severity":"breaking","affected_versions":"N/A (affects migration from `react-aria` hooks)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using named ES module imports: `import { Button } from 'react-aria-components'`.","cause":"Attempting to use CommonJS `require` syntax in a modern build setup, or incorrectly assuming a default export when components are named exports.","error":"TypeError: (0 , react_aria_components__WEBPACK_IMPORTED_MODULE_2__.Button) is not a function"},{"fix":"Add all necessary sub-components as children. For `TextField`, ensure `<Label>` and `<Input>` are present within the `<TextField>` component.","cause":"A composite component was rendered without its essential child components, violating its required structure for accessibility and functionality.","error":"Error: A `TextField` must contain an `Input` and a `Label`."},{"fix":"Ensure event handlers receive a function reference, e.g., `onPress={() => doSomething()}` or `onPress={doSomething}` (if `doSomething` is already a function), instead of `onPress={doSomething()}`.","cause":"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.","error":"Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate."},{"fix":"Verify the exact name of the component and ensure it's a named import: `import { CorrectComponentName } from 'react-aria-components'`.","cause":"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.","error":"Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined."}],"ecosystem":"npm"}