feat: S2 SideNav by snowystinger · Pull Request #10306 · adobe/react-spectrum

snowystinger · 2026-07-07T05:14:08Z

Closes

Early draft of SideNav for S2.

api is this right now:

<SideNav selectedRoute="/home"> // no onSelectionChange, control through router
  <SideNavItem href="/home">
    <SideNavContent>
      <SideNavLink>

decisions to make still

what are "categories"?
- They are just items that don't have a link in them, don't participate in selection and don't have the selection hover state. This will be problematic with our API as we don't know ahead of time if there will be a link or not.
- They can be mixed in the same SideNav, if it has children, it can either be a category or an item with a link.
how to stop focus from ever going to the "row/cell"
- Solved by forwarding events and re-firing them on the row from the link. This way you don't need to navigate to the row.
what happens to selection indicator if it's on an item inside a collapsed item/category?
- Figma shows that the item gets bolded and a different text color
does the selection indicator animate like Tabs do? what happens if it needs to move between levels?
- Design says no due to how far the indicator may need to move and how it indents

✅ 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:

🧢 Your Project:

rspbot · 2026-07-07T05:19:39Z

Build successful! 🎉

rspbot · 2026-07-09T06:15:23Z

Build successful! 🎉

rspbot · 2026-07-10T05:17:02Z

Build successful! 🎉

rspbot · 2026-07-10T05:27:16Z

Build successful! 🎉

rspbot · 2026-07-13T07:34:20Z

Build successful! 🎉

rspbot · 2026-07-13T07:38:27Z

Build successful! 🎉

rspbot · 2026-07-13T07:40:00Z

Build successful! 🎉

rspbot · 2026-07-13T08:38:35Z

Build successful! 🎉

LFDanLu · 2026-07-13T18:09:37Z

+  // RAC swallows arrow keys at the collection level (stopPropagation during capture), so a handler
+  // on the link never sees them. Intercept here on an ancestor, before RAC's row handler runs, and
+  // expand a collapsed row when the expand arrow is pressed while focus is on its link.
+  let onKeyDownCapture = (e: ReactKeyboardEvent) => {


I haven't pulled this down to try it myself, but perhaps you could make SideNav a keyboardNavigationBehavior = tab tree and have focusMode="child" and allowsArrowNavigation=true so that arrow up/down navigation still work but focus lands on the link by default. useGridList's handleTreeExpansionKeys will have to be updated to also check allowsArrowNavigation so that it can skip the
activeElement check below, but that might allow you to get rid of all this extra handling at this level

if (!('expandedKeys' in state) || activeElement !== rowRef) { return false; }

note that the extra props mentioned above are in #10159, so will require you to rebase/pull in that PR

Good news, textfield_gridlists is already my base :)
I attempted an implementation of the above and it appears to mostly work, so that's pretty awesome. I was missing that allowsArrowNavigation update when I tried those all together previously. Good thinking.

Just for posterity, there's a couple cases here:

Left/Right arrow to expand/collapse/traverse up that should still be accessible from the link.

In addition, focusMode="child" should only be the case for items with links (not categories) because then it might accidentally focus something like an ActionMenu that may be in the row regardless of if there is a Link.

Shift+Tab from a link should leave the SideNav.

rspbot · 2026-07-14T07:31:41Z

Build successful! 🎉

rspbot · 2026-07-15T00:39:18Z

Build successful! 🎉

rspbot · 2026-07-15T01:11:08Z

Build successful! 🎉

rspbot · 2026-07-15T01:39:22Z

Build successful! 🎉

rspbot · 2026-07-15T01:45:20Z

Build successful! 🎉

rspbot · 2026-07-15T02:14:15Z

Build successful! 🎉

rspbot · 2026-07-15T05:21:35Z

Build successful! 🎉

rspbot · 2026-07-15T22:48:04Z

Build successful! 🎉

rspbot · 2026-07-15T23:47:59Z

Build successful! 🎉

…v-rob

rspbot · 2026-07-20T18:43:36Z

Build successful! 🎉

rspbot · 2026-07-20T18:44:09Z

Build successful! 🎉

rspbot · 2026-07-21T02:02:06Z

Build successful! 🎉

rspbot · 2026-07-21T02:03:51Z

Build successful! 🎉

rspbot · 2026-07-21T02:11:05Z

Build successful! 🎉

rspbot · 2026-07-21T05:05:00Z

Build successful! 🎉

rspbot · 2026-07-21T07:06:00Z

Build successful! 🎉

rspbot · 2026-07-21T07:06:02Z

## API Changes

react-aria-components

/react-aria-components:GridListHeaderProps

+GridListHeaderProps {
+  children?: ReactNode
+  className?: string
+  id?: string
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>
+  style?: CSSProperties
+}

@react-spectrum/s2

/@react-spectrum/s2:SideNav

+SideNav <T> {
+  UNSAFE_className?: UnsafeClassName
+  UNSAFE_style?: CSSProperties
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  autoFocus?: boolean | FocusStrategy
+  children?: ReactNode | (T) => ReactNode
+  defaultExpandedKeys?: Iterable<Key>
+  dependencies?: ReadonlyArray<any>
+  disabledKeys?: Iterable<Key>
+  expandedKeys?: Iterable<Key>
+  id?: string
+  items?: Iterable<T>
+  onAction?: (Key) => void
+  onExpandedChange?: (Set<Key>) => any
+  selectedRoute: string
+  slot?: string | null
+  styles?: StylesPropWithHeight
+}

/@react-spectrum/s2:SideNavItem

+SideNavItem {
+  aria-label?: string
+  children: ReactNode
+  download?: boolean | string
+  hasChildItems?: boolean
+  href?: Href
+  hrefLang?: string
+  id?: Key
+  isDisabled?: boolean
+  onHoverChange?: (boolean) => void
+  onHoverEnd?: (HoverEvent) => void
+  onHoverStart?: (HoverEvent) => void
+  onPress?: (PressEvent) => void
+  onPressChange?: (boolean) => void
+  onPressEnd?: (PressEvent) => void
+  onPressStart?: (PressEvent) => void
+  onPressUp?: (PressEvent) => void
+  ping?: string
+  referrerPolicy?: HTMLAttributeReferrerPolicy
+  rel?: string
+  routerOptions?: RouterOptions
+  target?: HTMLAttributeAnchorTarget
+  textValue: string
+}

/@react-spectrum/s2:SideNavItemContent

+SideNavItemContent {
+  children: ReactNode
+}

/@react-spectrum/s2:SideNavItemLink

+SideNavItemLink {
+  children?: ReactNode
+}

/@react-spectrum/s2:SideNavSection

+SideNavSection <T extends {}> {
+  aria-label?: string
+  children?: ReactNode | (T) => ReactElement
+  dependencies?: ReadonlyArray<any>
+  id?: Key
+  items?: Iterable<T>
+}

/@react-spectrum/s2:SideNavHeader

+SideNavHeader {
+  children?: ReactNode
+  id?: string
+}

/@react-spectrum/s2:SideNavProps

+SideNavProps <T> {
+  UNSAFE_className?: UnsafeClassName
+  UNSAFE_style?: CSSProperties
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  autoFocus?: boolean | FocusStrategy
+  children?: ReactNode | (T) => ReactNode
+  defaultExpandedKeys?: Iterable<Key>
+  dependencies?: ReadonlyArray<any>
+  disabledKeys?: Iterable<Key>
+  expandedKeys?: Iterable<Key>
+  id?: string
+  items?: Iterable<T>
+  onAction?: (Key) => void
+  onExpandedChange?: (Set<Key>) => any
+  selectedRoute: string
+  slot?: string | null
+  styles?: StylesPropWithHeight
+}

/@react-spectrum/s2:SideNavItemProps

+SideNavItemProps {
+  aria-label?: string
+  children: ReactNode
+  download?: boolean | string
+  hasChildItems?: boolean
+  href?: Href
+  hrefLang?: string
+  id?: Key
+  isDisabled?: boolean
+  onHoverChange?: (boolean) => void
+  onHoverEnd?: (HoverEvent) => void
+  onHoverStart?: (HoverEvent) => void
+  onPress?: (PressEvent) => void
+  onPressChange?: (boolean) => void
+  onPressEnd?: (PressEvent) => void
+  onPressStart?: (PressEvent) => void
+  onPressUp?: (PressEvent) => void
+  ping?: string
+  referrerPolicy?: HTMLAttributeReferrerPolicy
+  rel?: string
+  routerOptions?: RouterOptions
+  target?: HTMLAttributeAnchorTarget
+  textValue: string
+}

/@react-spectrum/s2:SideNavItemContentProps

+SideNavItemContentProps {
+  children: ReactNode
+}

/@react-spectrum/s2:SideNavItemLinkProps

+SideNavItemLinkProps {
+  children?: ReactNode
+}

/@react-spectrum/s2:SideNavSectionProps

+SideNavSectionProps <T> {
+  aria-label?: string
+  children?: ReactNode | (T) => ReactElement
+  dependencies?: ReadonlyArray<any>
+  id?: Key
+  items?: Iterable<T>
+}

/@react-spectrum/s2:SideNavHeaderProps

+SideNavHeaderProps {
+  children?: ReactNode
+  id?: string
+}

rspbot · 2026-07-21T07:06:04Z

Agent Skills Changes

Added (1)

s2/skills/react-spectrum-s2/references/components/SideNav.md $\color{green}{+508}$

Modified (7)

react-aria/skills/react-aria/references/components/Separator/useSeparator.md $\color{green}{+1}$ $\color{red}{-1}$
react-aria/skills/react-aria/references/components/TokenField.md $\color{green}{+8}$ $\color{red}{-8}$
s2/skills/index.json $\color{green}{+1}$
s2/skills/react-spectrum-s2/SKILL.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/llms.txt $\color{green}{+1}$
s2/skills/react-spectrum-s2/references/react-aria/components/Separator/useSeparator.md $\color{green}{+1}$ $\color{red}{-1}$
s2/skills/react-spectrum-s2/references/react-aria/components/TokenField.md $\color{green}{+8}$ $\color{red}{-8}$

Install

React Spectrum S2:

npx skills add https://d1pzu54gtk2aed.cloudfront.net/pr/61323a1af0674fa94f02fc644e4219598e555b83/

React Aria:

npx skills add https://d5iwopk28bdhl.cloudfront.net/pr/61323a1af0674fa94f02fc644e4219598e555b83/

github-actions Bot added RAC S2 labels Jul 7, 2026

snowystinger marked this pull request as draft July 7, 2026 05:14

snowystinger changed the title ~~S2 sidenav rob~~ feat: S2 SideNav Jul 7, 2026

LFDanLu reviewed Jul 13, 2026

View reviewed changes

Comment thread packages/@react-spectrum/s2/src/SideNav.tsx

snowystinger marked this pull request as ready for review July 14, 2026 07:26

yihuiliao reviewed Jul 15, 2026

View reviewed changes

Comment thread packages/@react-spectrum/s2/src/SideNav.tsx Outdated

Comment thread packages/@react-spectrum/s2/src/SideNav.tsx Outdated

Comment thread packages/@react-spectrum/s2/src/SideNav.tsx Outdated

snowystinger added the ready for review label Jul 16, 2026

Base automatically changed from textfield_gridlists to main July 17, 2026 07:30

snowystinger added 3 commits July 20, 2026 11:35

feat: S2 SideNav

ec5b76d

hack a way for arrow key navigation to continue to work

0f81662

working

61049ce

snowystinger added 12 commits July 20, 2026 11:35

fix ts

16374ee

fix click interaction on Categories and disabled items

401d157

Move to GridList handling, fix colors, add tests and chromatic

14a29ff

lots of cleanup

1e606a5

remove useless test and add chromatic to replace it

c8a927f

fix lint

e9c0c11

fix required props, cleanup

f30af23

add tests and fix lost focus case

64e9965

restrict logic to tab keyboard nav

c7c9b24

fix docs ts

1073f01

review comments

6d0f7cf

fix label text wrapping

840dd76

LFDanLu force-pushed the s2-sidenav-rob branch from 05b4bcb to 840dd76 Compare July 20, 2026 18:37

Merge branch 'main' of github.com:adobe/react-spectrum into s2-sidena…

49b402c

…v-rob

snowystinger added 2 commits July 21, 2026 11:55

Fix keyboard navigation with sections

447c335

fix current selection bold

5eb6336

fix heights

85e88ff

snowystinger added 2 commits July 21, 2026 13:44

add press scaling to items

57e9445

fix lint

86ccd74

snowystinger added the release label Jul 21, 2026

setup alpha and card

61323a1

Uh oh!

Conversation

snowystinger commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

rspbot commented Jul 7, 2026

Uh oh!

rspbot commented Jul 9, 2026

Uh oh!

rspbot commented Jul 10, 2026

Uh oh!

rspbot commented Jul 10, 2026

Uh oh!

rspbot commented Jul 13, 2026

Uh oh!

rspbot commented Jul 13, 2026

Uh oh!

rspbot commented Jul 13, 2026

Uh oh!

rspbot commented Jul 13, 2026

Uh oh!

LFDanLu Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

snowystinger Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rspbot commented Jul 14, 2026

Uh oh!

rspbot commented Jul 15, 2026

Uh oh!

rspbot commented Jul 15, 2026

Uh oh!

rspbot commented Jul 15, 2026

Uh oh!

rspbot commented Jul 15, 2026

Uh oh!

rspbot commented Jul 15, 2026

Uh oh!

rspbot commented Jul 15, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rspbot commented Jul 15, 2026

Uh oh!

rspbot commented Jul 15, 2026

Uh oh!

rspbot commented Jul 20, 2026

Uh oh!

rspbot commented Jul 20, 2026

Uh oh!

rspbot commented Jul 21, 2026

Uh oh!

rspbot commented Jul 21, 2026

Uh oh!

rspbot commented Jul 21, 2026

Uh oh!

rspbot commented Jul 21, 2026

Uh oh!

rspbot commented Jul 21, 2026

Uh oh!

rspbot commented Jul 21, 2026

react-aria-components

/react-aria-components:GridListHeaderProps

@react-spectrum/s2

/@react-spectrum/s2:SideNav

/@react-spectrum/s2:SideNavItem

/@react-spectrum/s2:SideNavItemContent

/@react-spectrum/s2:SideNavItemLink

/@react-spectrum/s2:SideNavSection

/@react-spectrum/s2:SideNavHeader

/@react-spectrum/s2:SideNavProps

/@react-spectrum/s2:SideNavItemProps

snowystinger commented Jul 7, 2026 •

edited

Loading

LFDanLu Jul 13, 2026 •

edited

Loading

snowystinger Jul 14, 2026 •

edited

Loading