Skip to content

docs: add new React Aria hooks docs#10153

Open
reidbarber wants to merge 58 commits into
mainfrom
new-hook-docs
Open

docs: add new React Aria hooks docs#10153
reidbarber wants to merge 58 commits into
mainfrom
new-hook-docs

Conversation

@reidbarber

@reidbarber reidbarber commented Jun 2, 2026

Copy link
Copy Markdown
Member

Closes #5181

Migrates the React Aria component-level hook documentation to the new docs site.

Format is:

  • One interactive example that builds the component from the hook(s), instead of the old multi-example walkthrough.
  • Features and State management sections (we could potentially slim the Features content down)
  • Show API via FunctionAPI / InterfaceType
  • Composition over inline styling: Composite/overlay/picker hooks (useSelect, useComboBox, useDatePicker, the overlay hooks, etc.) reuse the styled vanilla-starter components (Button, Popover, Dialog, Calendar, ListBox, etc.) and feed the hook's return values in through context, following the "Reusing children" pattern. Leaf/primitive hooks build from scratch with minimal styling (reusing the vanilla CSS / design tokens for focus rings, etc.).

Not included / follow-ups:

  • useTree: RAC implements visible-row flattening + level handling outside useTreeState, might be too complex for now.
  • useAutocomplete: still beta, no existing example (we can add this though)

Open questions:

  • Should the descriptions be shortened? "Provides the behavior and accessibility implementation for a..." isn't helpful.
  • Some "Features" content is really lengthy (see useComboBox). Should we shorten this and have this content somewhere else, maybe a generic accessibility features page in the future?
  • Should these pages show up in search? Or should you go to the RAC page first.
  • Do we need pages for useFocusable or usePreventScroll?

✅ Pull Request Checklist:

  • Included link to corresponding React Spectrum GitHub Issue.
  • Added/updated unit tests and storybook for this change (for new code or code which already has tests).
  • Filled out test instructions.
  • Updated documentation (if it already exists for this component).
  • Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

Open the search menu and navigate to the Hooks section to see the new pages. Links are also featured under the "Related pages" section of the table of contents of the respective RAC component.

🧢 Your Project:

@rspbot

rspbot commented Jun 2, 2026

Copy link
Copy Markdown

@rspbot

rspbot commented Jun 2, 2026

Copy link
Copy Markdown

@devongovett

Copy link
Copy Markdown
Member

My initial thought last year when we were working on docs was that the hook docs would be more like how you'd use them together with RAC rather than building the components standalone (as our old docs did). Like for example the useSelect docs could reuse the Button/ListBox from RAC rather than re-creating them from scratch.

@rspbot

rspbot commented Jun 3, 2026

Copy link
Copy Markdown

@reidbarber reidbarber changed the title [WIP] docs: add new React Aria hooks docs docs: add new React Aria hooks docs Jun 8, 2026
@rspbot

rspbot commented Jun 8, 2026

Copy link
Copy Markdown

@snowystinger snowystinger left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

small problem with API rendering, it's all on one line:
Screenshot 2026-06-09 at 2 38 01 pm

I think this is a good start

Looks like first pass we aren't migrating collection related hooks to new collections yet?

@rspbot

rspbot commented Jun 9, 2026

Copy link
Copy Markdown

Comment thread packages/dev/s2-docs/pages/react-aria/Button/useButton.mdx Outdated
Comment thread packages/dev/s2-docs/pages/react-aria/Button/useButton.mdx Outdated
Comment thread packages/dev/s2-docs/pages/react-aria/Calendar/useCalendar.mdx Outdated
Comment thread packages/dev/s2-docs/pages/react-aria/Calendar/useCalendar.mdx Outdated
Comment thread packages/dev/s2-docs/pages/react-aria/Calendar/useCalendar.mdx Outdated
Comment thread packages/dev/s2-docs/pages/react-aria/Calendar/useCalendar.mdx Outdated
Comment thread packages/dev/s2-docs/pages/react-aria/DateRangePicker/useDateRangePicker.mdx Outdated
@devongovett

Copy link
Copy Markdown
Member

Good start! Added a few initial thoughts above. I think we'll also need to create a page at some point that describes when you'd want to use hooks, and explains that they can be used together with RAC (as some of the examples show here) or standalone, and how to do both.

@rspbot

rspbot commented Jun 11, 2026

Copy link
Copy Markdown

@rspbot

rspbot commented Jun 11, 2026

Copy link
Copy Markdown

@rspbot

rspbot commented Jun 11, 2026

Copy link
Copy Markdown

Agent Skills Changes

Added (92)
Modified (7)
Install

React Spectrum S2:

npx skills add https://d1pzu54gtk2aed.cloudfront.net/pr/caa94cb7778be1a348ad96d2e0067fee1eb464a8/

React Aria:

npx skills add https://d5iwopk28bdhl.cloudfront.net/pr/caa94cb7778be1a348ad96d2e0067fee1eb464a8/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Overlay not containing focus while using useModalOverlay

4 participants