react-stately

What is react-stately?

react-stately is a library that provides state management utilities for building accessible and robust React components. It is part of the React Spectrum collection of libraries developed by Adobe, which aims to provide a comprehensive set of tools for building adaptive, accessible, and robust user interfaces.

What are react-stately's main functionalities?

useListState

The useListState hook manages the state for a list of items, including selection and focus management. This example demonstrates how to initialize a list with some items and manage their state.

import { useListState } from 'react-stately';

function MyListComponent(props) {
  let state = useListState({
    initialSelectedKeys: ['item1'],
    items: [
      { key: 'item1', name: 'Item 1' },
      { key: 'item2', name: 'Item 2' },
      { key: 'item3', name: 'Item 3' }
    ]
  });

  return (
    <ul>
      {state.collection.map(item => (
        <li key={item.key}>{item.name}</li>
      ))}
    </ul>
  );
}

useToggleState

The useToggleState hook manages the state for a toggleable component, such as a checkbox or switch. This example shows how to create a button that toggles between 'Selected' and 'Not Selected' states.

import { useToggleState } from 'react-stately';

function MyToggleComponent() {
  let state = useToggleState();

  return (
    <button onClick={state.toggle}>
      {state.isSelected ? 'Selected' : 'Not Selected'}
    </button>
  );
}

useComboBoxState

The useComboBoxState hook manages the state for a combo box component, including input value and item selection. This example demonstrates how to create a combo box with a list of items.

import { useComboBoxState } from 'react-stately';

function MyComboBoxComponent(props) {
  let state = useComboBoxState({
    items: [
      { key: 'item1', name: 'Item 1' },
      { key: 'item2', name: 'Item 2' },
      { key: 'item3', name: 'Item 3' }
    ]
  });

  return (
    <div>
      <input
        value={state.inputValue}
        onChange={e => state.setInputValue(e.target.value)}
      />
      <ul>
        {state.collection.map(item => (
          <li key={item.key}>{item.name}</li>
        ))}
      </ul>
    </div>
  );
}

Other packages similar to react-stately

react-use

react-use is a collection of essential React hooks that cover a wide range of use cases, from state management to side effects. It provides hooks like useList, useToggle, and useInput, which offer similar functionalities to react-stately's useListState, useToggleState, and useComboBoxState, respectively. However, react-use is more general-purpose and not specifically focused on accessibility.

zustand

zustand is a small, fast, and scalable state management library for React. It provides a simple API for managing global state and can be used to create custom hooks for specific state management needs. While zustand is not specifically designed for accessibility, it offers a flexible and performant alternative to react-stately for managing component state.

react-spring

react-spring is a spring-physics-based animation library for React applications. It provides hooks for managing animated states, which can be used to create interactive and dynamic user interfaces. While react-spring is primarily focused on animations, it can complement react-stately by providing animated state transitions for components.

README

React Stately

A library of React Hooks that provides cross-platform state management for your design system.

Features

• 🏠 Foundational – React Stately provides the foundation and core logic for your component library. It handles state management for common components through an easy-to-use interface.
• 📱 Cross-platform – React Stately only provides state management, with no assumptions about the DOM or other view systems.
• ⚓️ Powered by React Hooks – React Stately is implemented as a library of React Hooks, which allows you to adapt them to your needs through composition.
• 🎨 Design agnostic – React Stately doesn’t make any assumptions about your design. It provides state management that’s intrinsic to the functionality of the component.

Getting started

The easiest way to start building a component library with React Stately is by following our getting started guide. It walks through all of the steps needed to install the hooks from npm, and create your first component.

Example

Here is a very basic example of using React Aria.

import {useRadioGroupState} from '@react-stately/radio';

function RadioGroup(props) {
  let state = useRadioGroupState(props);

  return (
    <>
      <label>
        <input
          type="radio"
          name={state.name}
          checked={state.selectedValue === 'dogs'}
          onChange={() => state.setSelectedValue('dogs')}
        />
        Dogs
      </label>
      <label>
        <input
          type="radio"
          name={state.name}
          checked={state.selectedValue === 'cats'}
          onChange={() => state.setSelectedValue('cats')}
        />
        Cats
      </label>
    </>
  );
}

<RadioGroup
  defaultValue="dogs"
  onChange={(value) => alert(`Selected ${value}`)}
/>

Learn more

React Stately is part of a family of libraries that help you build adaptive, accessible, and robust user experiences. Learn more about React Spectrum and React Aria on our website.