Registry / web-framework / react-stately

react-stately

JSON →
library3.46.0jsnpmunverified

React Stately is a JavaScript/TypeScript library developed by Adobe, providing highly accessible and robust state management hooks for complex UI components within the React ecosystem. It is a foundational part of the Adobe React Spectrum and React Aria libraries, focusing on managing component behavior and data without dictating visual presentation. This "headless" approach allows developers to build custom UIs while leveraging battle-tested accessibility and interaction patterns. As of April 2026, the current stable version is 3.46.0. The library follows a frequent release cadence, often with monthly or bi-monthly updates, reflecting ongoing feature development and improvements, especially in coordination with React Aria Components and React Spectrum S2. Its key differentiators include a strong emphasis on WAI-ARIA standards compliance, complex collection management (lists, grids, trees), and sophisticated interaction handling, making it suitable for enterprise-grade applications requiring high accessibility and performance.

npm install react-stately
INSTALL
IMPORT
SIG · REACT-STATELY
R
react-stately
web-frameworkjavascriptv3.46.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

useListState
import { useListState } from 'react-stately';
const { useListState } = require('react-stately');
Primarily consumed as an ESM module. CommonJS `require` should be avoided for modern React projects.
useSelectState
import { useSelectState } from 'react-stately';
import useSelectState from 'react-stately';
All provided hooks are named exports, not default exports.
useCheckboxGroupState
import { useCheckboxGroupState } from 'react-stately';
Manages state for a group of checkboxes.
CollectionBuilder
import { CollectionBuilder } from 'react-stately';
Used for building declarative collections in conjunction with <Item> and <Section> components.
Item
import { Item } from 'react-stately';
Used declaratively within CollectionBuilder or directly in components like <ListBox> to define collection items.

Demonstrates how to use `useListState` to manage selection state for a list of items, including toggling selection and programmatic state manipulation.

import { useListState } from 'react-stately'; import React from 'react'; interface Item { id: string; name: string; } const initialItems: Item[] = [ { id: '1', name: 'Apple' }, { id: '2', name: 'Banana' }, { id: '3', name: 'Orange' } ]; function MyStatefulList() { const state = useListState<Item>({ items: initialItems, selectionMode: 'multiple', onSelectionChange: (keys) => { console.log('Current selected keys:', Array.from(keys)); // In a real app, you would update your UI based on this state. // E.g., render selected items or highlight them. }, getKey: (item) => item.id, }); const toggleItem = (id: string) => { if (state.selectionManager.isSelected(id)) { state.selectionManager.toggleSelection(id); } else { state.selectionManager.addSelection(id); } }; return ( <div style={{ padding: '20px', border: '1px solid #ccc', borderRadius: '5px' }}> <h3>List State Management Example</h3> <p>Click items to toggle selection:</p> <ul style={{ listStyle: 'none', padding: 0, margin: 0 }}> {[...state.collection].map((item) => ( <li key={item.key} onClick={() => toggleItem(item.key)} style={{ padding: '8px', cursor: 'pointer', background: state.selectionManager.isSelected(item.key) ? '#e0f7fa' : 'white', borderBottom: '1px solid #eee' }} > {item.value?.name} {state.selectionManager.isSelected(item.key) && ' (Selected)'} </li> ))} </ul> <p style={{ marginTop: '15px' }}> Selected IDs: {Array.from(state.selectionManager.selectedKeys).join(', ') || 'None'} </p> <button onClick={() => state.selectionManager.clearSelection()} style={{ marginTop: '10px', padding: '8px 15px', cursor: 'pointer' }} > Clear Selection </button> <button onClick={() => state.selectionManager.selectAll()} style={{ marginTop: '10px', marginLeft: '10px', padding: '8px 15px', cursor: 'pointer' }} > Select All </button> </div> ); } export default MyStatefulList;
Debug
Known issues
gotchaReact Stately is a 'headless' state management library, meaning it provides state and logic but no visual UI or accessibility attributes. It is typically used in conjunction with `react-aria` (for accessible DOM properties and interactions) or `@react-spectrum/s2` (for Adobe's Spectrum Design System components). Using React Stately alone requires manual implementation of significant ARIA attributes and event handling for accessibility.
fix
Consider pairing `react-stately` with `react-aria` for full accessibility and interaction logic, or `@react-spectrum/s2` for pre-built components.
affects: >=3.0.0
gotchaThe `CollectionBuilder`, `Item`, and `Section` components/utilities, while powerful for declarative collection definition, can be complex. Incorrect usage, especially with dynamic data or deeply nested structures, can lead to incorrect keys, hydration mismatches, or rendering issues.
fix
Ensure `getKey` prop is correctly implemented for all items to provide stable, unique keys. Thoroughly test dynamic collection updates and nested structures.
affects: >=3.0.0
gotchaWhen using `react-stately` hooks with TypeScript, it is crucial to provide correct generic types (e.g., `useListState<MyItemType>`). Failure to do so can result in `any` types, loss of type safety, or type errors when accessing properties from `state.collection` or item values.
fix
Always explicitly define the generic type parameter for hooks like `useListState`, `useSelectState`, etc., based on the shape of your data items.
affects: >=3.0.0
breakingThe library primarily uses named exports and is designed for ESM environments. While bundlers usually handle CJS compatibility, direct `require()` statements for specific symbols might not work as expected in certain setups or older Node.js versions.
fix
Always use ES module `import` syntax (e.g., `import { useListState } from 'react-stately';`). Ensure your build setup correctly processes ES modules.
affects: >=3.0.0
Errors
Common errors & fixes
Error: Hooks can only be called inside of the body of a function component.
`react-stately` hooks, like all React hooks, must be called directly within a React functional component or a custom hook.
fix
Ensure `useListState` or other `react-stately` hooks are called at the top level of your functional component, not inside loops, conditions, or nested functions.
TypeError: state.collection is not iterable
This typically occurs if the `items` prop was not provided or was provided incorrectly to `useListState` (or similar hooks), leading to an uninitialized or improperly formed collection object.
fix
Verify that the `items` array passed to `useListState` is correctly formatted and not `null` or `undefined`. Ensure `getKey` is also provided if items don't have a default `id` or `key` property.
Warning: Each child in a list should have a unique "key" prop.
When rendering items from `state.collection` within a React list, React requires a unique `key` prop for each item to efficiently track changes. This can happen if `getKey` is not specified or returns non-unique values.
fix
Provide a stable and unique `getKey` function in the `useListState` (or similar hook) options, or explicitly set a `key` prop on your rendered elements using `item.key` or a truly unique identifier from `item.value`.
Property 'value' does not exist on type 'unknown' (or 'any')
This happens when accessing `item.value` from an item retrieved from `state.collection` without providing the correct generic type to the `useListState` hook.
fix
Define the generic type for the hook, e.g., `const state = useListState<MyItemType>({ items: ..., ... });`. This ensures `item.value` is correctly typed as `MyItemType`.
Upgrade
Version history
3.46.0latest on npm
Audit
Dependencies
reactrequiredReact is a peer dependency required for all hooks and components provided by this library.
Agent activity
4 hits · last 30 days
node
4
Resources
react-stately — npm install react-stately · libregistry