Getting started

How to install React Aria and build your first component.

Install

Install React Aria with your preferred package manager.

Quick start

The documentation for each component includes vanilla CSS and Tailwind examples. Copy and paste these into your project and make them your own. You can also download each example as a ZIP or open in CodeSandbox or StackBlitz.

import {Select, SelectItem} from './Select';

<Select label="Favorite animal">
  <SelectItem>Aardvark</SelectItem>
  <SelectItem>Cat</SelectItem>
  <SelectItem>Dog</SelectItem>
  <SelectItem>Kangaroo</SelectItem>
  <SelectItem>Panda</SelectItem>
  <SelectItem>Snake</SelectItem>
</Select>

shadcn CLI

Each example can also be installed with the shadcn CLI. This will add the component source code, styles, and all dependencies to your project automatically.

Storybook starter kits

If you're building a full component library, download a pre-built Storybook starter kit. These include every component in a standalone development environment.

Working with AI

Use the menu at the top of each page in the docs to open or copy it into your favorite AI assistant. We also have an MCP server which can be used directly in your IDE, and lms.txt which can help AI agents navigate the docs.

Build a component from scratch

In this tutorial, we'll build a custom Select component.

1. Import and assemble the parts

   Each React Aria component renders a single DOM element. Complex components like Select compose together multiple parts to build a complete pattern.

   import {Button, Label, ListBox, ListBoxItem, Popover, Select, SelectValue} from 'react-aria-components';
   
   <Select>
     <Label>Favorite Animal</Label>
     <Button>
       <SelectValue />
     </Button>
     <Popover>
       <ListBox>
         <ListBoxItem>Cat</ListBoxItem>
         <ListBoxItem>Dog</ListBoxItem>
         <ListBoxItem>Kangaroo</ListBoxItem>
       </ListBox>
     </Popover>
   </Select>
   

2. Add your styles

   React Aria does not include any styles by default, allowing you to build custom designs to fit your application or design system. You can use any styling solution, including vanilla CSS, Tailwind CSS, CSS-in-JS, etc.

   Each React Aria component includes a default class name to use in your CSS, and data attributes for states such as pressed, hovered, selected, etc.

   .react-aria-ListBoxItem {
     color: black;
   
     &[data-selected] {
       background: black;
       color: white;
     }
   }
   

   You can also override these defaults with a custom className prop, and access states via render props. Check out our styling guide to learn more.

3. Create a reusable component

   To reuse styles throughout your project, wrap all of the parts into a reusable component. Create your own API by extending React Aria's types with additional props. Components such as Popover can also be shared with other patterns so they don't need be styled separately each time.

   import type {SelectProps as AriaSelectProps, ListBoxItemProps} from 'react-aria-components';
   import {Select as AriaSelect, Button, Label, ListBox, ListBoxItem, SelectValue} from 'react-aria-components';
   import {Popover} from './Popover';
   import './Select.css';
   
   export interface SelectProps extends AriaSelectProps {
     label?: string
   }
   
   export function Select(props: SelectProps) {
     return (
       <AriaSelect {...props}>
         <Label>{props.label}</Label>
         <Button className="select-button">
           <SelectValue />
         </Button>
         <Popover>
           <ListBox className="select-listbox">
             {props.children}
           </ListBox>
         </Popover>
       </AriaSelect>
     );
   }
   
   export function SelectItem(props: ListBoxItemProps) {
     return <ListBoxItem {...props} className="select-item" />;
   }
   

4. Use your component

   Now you can render a consistently styled <Select> anywhere in your project!

   import {Select, SelectItem} from './Select';
   
   function App() {
     return (
       <Select label="Favorite animal">
         <SelectItem>Cat</SelectItem>
         <SelectItem>Dog</SelectItem>
         <SelectItem>Kangaroo</SelectItem>
       </Select>
     );
   }
   

Framework setup

React Aria works out of the box in any React framework. When you're ready, follow our framework setup guide to optimize the bundle size, configure internationalization, and integrate with client side routers.