{"id":11650,"library":"react-aria","title":"React Aria","description":"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.","status":"active","version":"3.48.0","language":"javascript","source_language":"en","source_url":"https://github.com/adobe/react-spectrum","tags":["javascript","typescript"],"install":[{"cmd":"npm install react-aria","lang":"bash","label":"npm"},{"cmd":"yarn add react-aria","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-aria","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for all React-based components and hooks.","package":"react","optional":false},{"reason":"Required as a peer dependency for DOM rendering and interaction.","package":"react-dom","optional":false}],"imports":[{"note":"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.","wrong":"const { useButton } = require('react-aria');","symbol":"useButton","correct":"import { useButton } from 'react-aria';"},{"note":"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.","wrong":"import useFocusRing from 'react-aria/useFocusRing';","symbol":"useFocusRing","correct":"import { useFocusRing } from 'react-aria';"},{"note":"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.","symbol":"mergeProps","correct":"import { mergeProps } from 'react-aria';"}],"quickstart":{"code":"import React from 'react';\nimport { useButton } from 'react-aria';\nimport { mergeProps } from 'react-aria';\n\ninterface MyButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {\n  onPress?: () => void;\n}\n\nfunction MyButton(props: MyButtonProps) {\n  let ref = React.useRef<HTMLButtonElement>(null);\n  let { buttonProps, isPressed } = useButton(props, ref);\n\n  return (\n    <button\n      {...mergeProps(buttonProps, props)}\n      ref={ref}\n      style={{\n        backgroundColor: isPressed ? 'darkblue' : 'blue',\n        color: 'white',\n        padding: '10px 20px',\n        border: 'none',\n        borderRadius: '5px',\n        cursor: 'pointer'\n      }}\n    >\n      {props.children}\n    </button>\n  );\n}\n\n// Example usage in a component\nexport function App() {\n  const handlePress = () => {\n    console.log('Button pressed!');\n    alert('Hello from React Aria Button!');\n  };\n\n  return (\n    <div>\n      <h1>React Aria Quickstart</h1>\n      <MyButton onPress={handlePress}>Click Me</MyButton>\n    </div>\n  );\n}","lang":"typescript","description":"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."},"warnings":[{"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.","message":"React 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"While `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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: Cannot read properties of null (reading 'focus')"},{"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`.","cause":"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.","error":"Accessibility warning: 'Some element' must have a label accessible to screen readers, or you must provide an `aria-label` or `aria-labelledby` prop."}],"ecosystem":"npm"}