feat: add support for tree sections by yihuiliao · Pull Request #9013 · adobe/react-spectrum

yihuiliao · 2025-10-10T05:50:27Z

Closes

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

Test RAC Tree examples both those with and without sections. It would also be good to sanity check S2 and v3 TreeView since they are built on top of RAC Tree.

🧢 Your Project:

…tenTree

rspbot · 2025-10-10T05:55:21Z

Build successful! 🎉

rspbot · 2025-10-10T22:19:22Z

Build successful! 🎉

rspbot · 2025-10-10T22:25:04Z

Build successful! 🎉

rspbot · 2025-10-10T22:45:37Z

Build successful! 🎉

yihuiliao · 2025-10-10T22:14:32Z

packages/@react-aria/gridlist/src/useGridListItem.ts

      if (parent) {
        // siblings must exist because our original node exists
-        let siblings = state.collection.getChildren?.(parent.key)!;
+        let siblings = getDirectChildren(parent as CollectionNode<T>, state.collection as Collection<CollectionNode<T>>);


we used to use the getChildren method from TreeCollection but now that we've changed it to get ALL the descendants of a parent node instead of its immediate descendants, we can't use that anymore. i decided to make a new function called getDirectChildren which is essentially the same code as what getChildren was before

packages/react-aria-components/src/Tree.tsx

yihuiliao · 2025-10-10T22:30:18Z

packages/react-aria-components/src/Tree.tsx

  let [expandedKeys, setExpandedKeys] = useControlledState(
-    propExpandedKeys ? convertExpanded(propExpandedKeys) : undefined,
-    propDefaultExpandedKeys ? convertExpanded(propDefaultExpandedKeys) : new Set(),
+    propExpandedKeys ? new Set(propExpandedKeys) : undefined,


ended up getting rid of convertExpanded because i was running into a type error where expandedKeys could either be a Set or string but since propExpandedKeys/propDefaultExpandedKeys are type Iterable<Key> and cannot be set to all, there wasn't any way expandedKeys would ever be a string

yihuiliao · 2025-10-10T23:19:46Z

packages/react-aria-components/src/Tree.tsx

+    }
+
+    if ((this.expandedKeys.has(node.key) || node.type !== 'item') && node.firstChildKey != null) {
+      return node.firstChildKey;


should getKeyAfter include content nodes or should it skip them?

in this case, if the node is included in expandedKeys, we'll look at its firstChildKey which will be a TreeItemContent node. however, this caused issues in DropTargetKeyboardNavigation so we check if the node is a content node and if it is, we check its nextKey. however, we could deal with that here but depends on what we want to do

rspbot · 2025-10-10T23:26:46Z

Build successful! 🎉

rspbot · 2026-02-11T01:34:18Z

Build successful! 🎉

LFDanLu

The behavior looks good, we should do some more through testing for accessibility and DnD if possible. Noted some small areas that I had some questions in

packages/@react-aria/dnd/src/DropTargetKeyboardNavigation.ts

packages/@react-aria/gridlist/src/useGridListItem.ts

LFDanLu · 2026-02-11T18:43:50Z

packages/react-aria-components/src/Collection.tsx

w/ regards to rendering the drop indicator, did we test DnD with Tree sections yet? I think I remember a potential problem being the drop indicators rendered after the last row in a section and the first row in the next section and those being conflated as being the same when they aren't in practice

yeah dnd is unlikely to work (it also doesn't work in listbox w/ sections and gridlist w/ sections). we decided for gridlist to leave it as a follow-up since we knew we were releasing it as an alpha and i think the same would apply here

how are we releasing this as an alpha?

i guess the package itself wouldn't say anything about it being alpha but with gridlist we just marked it as an alpha on the docs. we could also add unstable to the export

If we do the UNSTABLE, eventually we have to remove it but also keep it around
Ok, so we're just doing it via the docs

LFDanLu · 2026-02-11T18:47:52Z

packages/react-aria-components/stories/Tree.stories.tsx

  }
 };

+const TreeExampleSectionRender = (args) => (


I noticed in this story that the very last item is getting a posinset=4 but a setsize=2 so it seems to be counting the sections themselves for the posinset but not in the total size. Should sections be counted?

ah right this is a similar issue to the aria-rowindex in GridList Sections that i tried to solve in a different pr when there's a mix of sections + individual items.

based on your comment here #8790 (comment) this mixed case might not be something we support but i can't remember what we resolution was in otters...so maybe this story is a bit contrived since i just copied it from another example and added section to it

but regardless, aria-posinset is calculated using node.index, so we'd need more complicated logic to correct this but the calculations for that can get expensive so we wanted to do it in the collection somehow

that said, i have been thinking about this aria-posinset and aria-setsize and i don't think our values are quite right. it would probably take a overhaul of how we determine the index/size with each node (again going back to the accessibility issues in gridlist sections).

i think the setsize and posinset should reference rows with the same level even across sections but right now, we calculate setsize and posinset per section rather than the entire tree

what we have tho won't mess things up for current trees, just those with sections really

That sounds fine, we can tie it to #9556

packages/@react-aria/selection/src/ListKeyboardDelegate.ts

packages/react-aria-components/src/Tree.tsx

snowystinger

How do I get VO to read the section titles?

packages/@react-stately/layout/src/ListLayout.ts

packages/react-aria-components/src/Tree.tsx

snowystinger · 2026-02-11T23:24:01Z

packages/react-aria-components/src/Tree.tsx

+
+  return (
+    <dom.section
+      {...mergeProps(DOMProps, renderProps, rowGroupProps)}


do we need UNSAFE or style props?

what about labelable? or global events? I'm unable to navigate to the section title, and I also don't hear it in the VO announcements for rows inside the section. So possibly global events doesn't make sense, but I assume we should be able to get labels

you shouldn't be able to navigate to the section title. we've never had titles be focusable

this also isn't S2 TreeView so no need for UNSAFE or style props. the renderProps should handle that i believe

derp, i noticed that it wasn't S2 after i wrote that comment, apologies for the noise

Outstanding question, how do we expect VO to announce Sections given that you can't get to them?

sorry i was investigating this one a bit. for listbox sections, the section will get announced with the item. this just seems to be the supported VO behavior. but hat doesn't seem to be the case with gridlist sections/tree sections.

i made a minimal reproduction of it in this codepen: https://codepen.io/yihuiliao/pen/MYeLPMj

in comparison, here's what listbox does: https://codepen.io/yihuiliao/pen/MYeLzaJ
for me, it doesn't always announce the section it's in. it only announces the section when you change from one section to another, but better than what's happening in grids.

im thinking about how we could get around it, maybe by passing the section/heading as an aria-labelledby to the items in it?

might be worthwhile asking the accessibility team about this, hopefully we don't have to implement custom announcements

yihuiliao · 2026-02-12T00:58:49Z

pushed up a couple changes but will get to the rest of the comments tomorrow if they are not marked as resolved or have no comments/reactions

rspbot · 2026-02-12T01:06:00Z

Build successful! 🎉

reidbarber

Behavior looks good! Just a few small comments:

packages/@react-aria/gridlist/src/useGridListItem.ts

packages/react-aria-components/src/Tree.tsx

rspbot · 2026-02-12T19:24:18Z

Build successful! 🎉

snowystinger

pretty close, I got held up here for a while though trying to decipher between name and behaviour

packages/@react-aria/selection/src/ListKeyboardDelegate.ts

rspbot · 2026-02-13T18:16:33Z

Build successful! 🎉

rspbot · 2026-02-13T18:16:35Z

## API Changes

react-aria-components

/react-aria-components:TreeHeader

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

/react-aria-components:TreeSection

+TreeSection <T extends {}> {
+  aria-label?: string
+  children?: ReactNode | ({}) => ReactElement
+  className?: string
+  dependencies?: ReadonlyArray<any>
+  id?: Key
+  items?: Iterable<{}>
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>
+  style?: CSSProperties
+  value?: {}
+}

yihuiliao added 15 commits September 23, 2025 15:08

initial tree stuff

473d209

fix virtualized tree section expanding, update methods to remove flat…

e896397

…tenTree

cleanup

c3385c1

more cleanup

fb17656

Merge branch 'main' into tree-section

a1c8b17

update key after if its content node

89df42f

fix types when checking content node

8491826

fix spacing

6f78fe7

update dynamic story

43f2895

update setSize with added getDirectChildren function

99d4169

fix types, update at method

049f2a5

remove console logs

fce9dce

add collection dependency to gridlist

f138f6a

fix lint

900d69e

update yarn lock

ae36ec5

yihuiliao added 4 commits October 10, 2025 15:03

rename dynamic row section array

cff1b4c

add tests, fix setSize for top level nodes inside a section

e6752ca

fix lint

fb703b2

remove comments

98289ce

more cleanup

ed55388

comments and stuff

3facc4a

yihuiliao commented Oct 10, 2025

View reviewed changes

yihuiliao changed the title ~~wip: tree section~~ feat: add support for tree sections Oct 10, 2025

yihuiliao marked this pull request as ready for review October 10, 2025 23:20

LFDanLu reviewed Feb 11, 2026

View reviewed changes

simplify logic for visible/non disabled item

8f668a2

snowystinger reviewed Feb 11, 2026

View reviewed changes

comments, small fixes

29e729d

github-actions bot added the v3 label Feb 12, 2026

yihuiliao removed the v3 label Feb 12, 2026

reidbarber reviewed Feb 12, 2026

View reviewed changes

packages/@react-aria/gridlist/src/useGridListItem.ts Outdated Show resolved Hide resolved

packages/react-aria-components/src/Tree.tsx Outdated Show resolved Hide resolved

yihuiliao added 4 commits February 12, 2026 10:28

make guarding against content node more robust

564646d

optimize filtering content nodes in list layout

3d8b288

optimize getting child array

d209f52

add helper function for cloning

f1088a1

github-actions bot added the v3 label Feb 12, 2026

snowystinger reviewed Feb 12, 2026

View reviewed changes

packages/@react-aria/selection/src/ListKeyboardDelegate.ts Show resolved Hide resolved

reidbarber previously approved these changes Feb 13, 2026

View reviewed changes

add comments

421f22f

yihuiliao dismissed reidbarber’s stale review via 421f22f February 13, 2026 18:08

github-actions bot removed the v3 label Feb 13, 2026

reidbarber approved these changes Feb 13, 2026

View reviewed changes

LFDanLu approved these changes Feb 13, 2026

View reviewed changes

LFDanLu added this pull request to the merge queue Feb 13, 2026

Merged via the queue into main with commit 5847e26 Feb 13, 2026
29 checks passed

LFDanLu deleted the tree-section branch February 13, 2026 18:45

yihuiliao added the TreeView label Feb 14, 2026

Conversation

yihuiliao commented Oct 10, 2025 • 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 Oct 10, 2025

Uh oh!

rspbot commented Oct 10, 2025

Uh oh!

rspbot commented Oct 10, 2025

Uh oh!

rspbot commented Oct 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Oct 10, 2025

Uh oh!

rspbot commented Feb 11, 2026

Uh oh!

LFDanLu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yihuiliao Feb 11, 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!

yihuiliao Feb 12, 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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

snowystinger left a comment • 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!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yihuiliao Feb 12, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yihuiliao Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

yihuiliao commented Oct 10, 2025 •

edited

Loading

yihuiliao Feb 11, 2026 •

edited

Loading

yihuiliao Feb 12, 2026 •

edited

Loading

snowystinger left a comment •

edited

Loading

yihuiliao Feb 12, 2026 •

edited

Loading

yihuiliao Feb 12, 2026 •

edited

Loading