feat: Add `CollectionNode` to collection renderer by nwidynski · Pull Request #8523 · adobe/react-spectrum

nwidynski · 2025-07-10T14:42:40Z

This adds an optional CollectionNode component to the collection renderer interface, which enables customization of a nodes render output without having to re-implement the entire renderer. This can be useful to build wrapper components which modify a nodes pseudo content without breaking an existing custom renderer, e.g. <Virtualizer />.

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

nwidynski · 2025-07-11T12:51:04Z

@devongovett Would love to hear your thoughts on this. For more context, this PR relates to #8317 (comment). Let me know if the docs need updates as well here!

devongovett · 2025-07-12T00:57:48Z

So you are looking for some kind of "inheritance" for collection renderers basically? Like use virtualizer but add an extra wrapper element around items? Can you describe in a bit more detail how your use case (a carousel I guess?) works?

One concern is that it could be somewhat easy to mess up the DOM structure expected by an existing renderer, but maybe it's an advanced use case anyway so you know the risks.

I was going to say the default collection renderer was pretty simple so it wouldn't be too hard to copy, but the drop indicator stuff is kinda complicated now so maybe this makes sense.

Do you usually want to wrap just the item itself or also wrap the drop indicators?

Sorry for all the questions just trying to think through the use cases here.

nwidynski · 2025-07-12T01:17:23Z

@devongovett Yes, thats right! The primary idea for this PR was to be able to create a component similar to Autocomplete, which composes around a collection component and is able to modify the content after/before the drop indicator. More specifically, we were simulating an infinite loop of collection items by rendering clones of the opposite collection side (e.g. item n-1 before item 1) at the first and last collection item respectively, then moving scroll position when hitting the boundaries. This meant we had to place clones outside of the drop indicators, which otherwise would be pushed out of view.

PS: We have already moved on from this implementation to one based on a Virtualizer, but nevertheless this PR would make sense i feel like. More on our implementation soon, as I will try to contribute the full Carousel!

devongovett · 2025-07-16T01:20:14Z

Got it, thanks. I think something like that makes sense but I haven't fully thought it through yet. We're in release mode at the moment so responses might be slow. Will discuss it with the team soon.

devongovett

We discussed this as a team and we think this is a reasonable API addition. Just one question on prop naming in case you have some ideas.

devongovett · 2025-07-25T00:59:25Z

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

+  /** The content that should be rendered before the item. */
+  before?: ReactNode,
+  /** The content that should be rendered after the item. */
+  after?: ReactNode


Do you think we should name these props so they are more specific to drop indicators? Not sure if we might want to add other things between items in the future, whether we'd want to group them here or allow them to be passed in separately for more control.

I was questioning the same while working on this. Personally, I do feel like a user of this feature is looking for as much control here as possible. A compromise between the two could maybe be to change the signature to ReactNode[] or ReactElement[] to make destructuring much easier.

@devongovett Btw, since I saw your reply on X, we might want to offer a wrapper prop here as well to wrap the node. Maybe thats easier than cloning the node just to modify its render function.

Apologies for the very late reply. Personally, I think keeping the naming as is but expanding the signature to what you've proposed above is what I'd lean towards. The wrapper prop (and the itemRef addition you've mentioned in other comments) seems fine as well but in the hopes of getting this in sooner rather than later we can make those follow ups if you are fine with that.

Sounds good, I will do the follow ups in another PR tmrw 👍 Feel free to push the changes for the signatures if you intend to merge it today, since im out of office already.

nwidynski · 2025-08-10T21:20:53Z

@devongovett Have you had the chance to make a decision on naming? Just bumping to get this PR wrapped up.

PS: I would also love to support an itemRef, which is passed to the nodes render function and merged with the normal ref. Happy to postpone any further changes to follow ups however, lmk 👍

nwidynski · 2026-01-12T16:13:51Z

Can we tie this up? Please also let me know about the itemRef prop, which would be used to get a handle on the underlying DOM element of a collection item from a parent collection renderer. Underlying implementation of this would be:

CollectionBuilder.tsx

let Component = forwardRef(({node}: {node: Node<any>}, ref: ForwardedRef<E>) => render(node.props, mergeRefs(node.props.ref, ref), node));

nwidynski

@LFDanLu I added the nodeRef and render wrapper function as discussed. This should be good for review now 👍

nwidynski · 2026-02-20T16:50:43Z

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

    items: parent ? collection.getChildren!(parent.key) : collection,
-    dependencies: [renderDropIndicator],
+    dependencies: [CollectionNode, parent, renderDropIndicator],


Adding parent here doesn't do a whole lot, since collection.getChildren returns a new iterator on every render anyways. Still added it just in case that ever becomes identity stable.

snowystinger · 2026-03-14T00:06:11Z

packages/@react-types/shared/src/collections.d.ts

  shouldInvalidate?: (context: any) => boolean,
  /** A function that renders this node to a React Element in the DOM. */
-  render?: (node: Node<any>) => ReactElement
+  render?: (node: Node<any>, ref?: ForwardedRef<Element>) => ReactElement


Is this necessary? doesn't node have the ref on it?

I wanted to avoid mutating the node props outside of the builder if that makes sense. Using mergeProps in CollectionBuilder means any ref a parent renderer wants to attach to this node is resolved just-in-time before hitting the render function.

Also, while I appreciate you taking the time, you might want to defer review to next week here, haha. I'm about to replace this PR with a new one that opens up Virtualizer properly to be able to inherit not only the "CollectionNode", but also "CollectionRoot", since that's required to make the carousel work.

I was just kept busy with the RFC today 😅

devongovett

I'm wondering if this is the right API. It sounds like what you want is collection renderer composition, and I agree in principle that would be nice, but that is kind of left up to the implementor at the moment. Virtualizer does not currently "extend" the default renderer (it re-implements rendering drop indicators for example), and there's no way to control the order things are wrapped. Ideally they would compose in the order you nest them in the JSX tree.

<DefaultCollectionRenderer>
  <Virtualizer>
    <MySpecialWrapper>
      <ListBox>

In this case, the items should be wrapped so that MySpecialWrapper goes inside the absolutely positioned Virtualizer wrapper. And ideally Virtualizer wouldn't need to re-implement rendering the drop indicators (though they also get wrapped with absolutely positioned elements), it should inherit that behavior from the DefaultCollectionRenderer, and these should be outside the Virtualizer item wrapper. I haven't thought of exactly what the API should be yet, but feels like it should be doable with function composition.

Also not quite sure if it's worth the complexity if we don't have a strong need for it though. An alternative could be to simply export more things so it's easier to create custom renderers (e.g. export functions for rendering drop indicators).

devongovett · 2026-03-14T00:06:33Z

packages/@react-types/shared/src/collections.d.ts

  shouldInvalidate?: (context: any) => boolean,
  /** A function that renders this node to a React Element in the DOM. */
-  render?: (node: Node<any>) => ReactElement
+  render?: (node: Node<any>, ref?: ForwardedRef<Element>) => ReactElement


Do we need this? Can you get the ref via node.props.ref?

#8523 (comment)

devongovett · 2026-03-14T01:07:31Z

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

-      return item?.render?.(item);
-    },
+    // If we don't skip rendering the node here, we end up rendering them twice.
+    renderView: () => null,


this will negate the caching done by Virtualizer.

Do you have alternate suggestions on how to approach that? Getting the rendered output within the inherited DefaultCollectionNode is pretty difficult.

devongovett · 2026-03-14T01:14:52Z

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

+      pseudoProps = {before: new Array(beforeIndicator), after: new Array(afterIndicator)};
+    }
+
+    let render = (item: Node<unknown>, itemRef?: ForwardedRef<Element>) => (


This will end up wrapping the original element and not the wrapper from the renderer's CollectionNode implementation. Won't that cause issues with positioning? The virtualizer wrapper adds position: absolute but any before or after content you add inside your custom CollectionNode won't be added inside that and won't get positioned correctly. The problem is you don't control the order the wrapping occurs. I think the order things get wrapped should match the order you nest collection renderers in the JSX tree.

Yes, agreed also. Its done that way in the coming revision 😅 Sorry about the wasted time here.

nwidynski · 2026-03-14T02:02:51Z

@devongovett #8523 (comment)

I fully agree, hence why I asked to defer review to next week 😅 . I have pretty much finished up a rework of this PR to do exactly what you said here with function composition. I'm just putting the finishing touches on, since our RFC conversation took up the majority of today.

snowystinger · 2026-03-14T02:09:29Z

May we close this one if another is superseding it? We're auditing to minimise merge conflicts with a really large PR

nwidynski · 2026-03-14T02:10:19Z

Yes, we can close this one temporarily.

nwidynski added 2 commits July 10, 2025 16:29

feat: add node component to collection renderer

3b82fb5

fix: drop indicators

d6210b6

LFDanLu mentioned this pull request Jul 15, 2025

Feat: Add support for horizontal orientation to GridList & ListBox #8533

Merged

5 tasks

devongovett reviewed Jul 25, 2025

View reviewed changes

nwidynski mentioned this pull request Aug 10, 2025

feat: support sections and headers in RAC gridlist #8667

Merged

5 tasks

nwidynski mentioned this pull request Nov 21, 2025

chore: Carousel or Image Rotator RFC #9084

Open

5 tasks

nwidynski mentioned this pull request Dec 11, 2025

Table components: Refs are not set in first render #9325

Open

Merge branch 'main' into collection-node

cdb2f7d

github-actions bot added RAC S2 labels Feb 20, 2026

nwidynski added 2 commits February 20, 2026 17:46

feat: nodeRef & render inheritance

24a20ad

chore: naming

21ca388

nwidynski commented Feb 20, 2026

View reviewed changes

nwidynski added 2 commits February 20, 2026 18:15

fix: remove spread operator

c42a639

fix: tests in react 16

09c8ffe

devongovett force-pushed the main branch from 8df1873 to a6e720d Compare March 4, 2026 00:20

Merge branch 'main' into collection-node

ba705a0

snowystinger reviewed Mar 14, 2026

View reviewed changes

devongovett reviewed Mar 14, 2026

View reviewed changes

nwidynski closed this Mar 14, 2026

Conversation

nwidynski commented Jul 10, 2025

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

nwidynski commented Jul 11, 2025

Uh oh!

devongovett commented Jul 12, 2025

Uh oh!

nwidynski commented Jul 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devongovett commented Jul 16, 2025

Uh oh!

devongovett left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nwidynski Jul 25, 2025 • 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!

nwidynski Jul 27, 2025 • 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!

nwidynski commented Aug 10, 2025

Uh oh!

nwidynski commented Jan 12, 2026

Uh oh!

nwidynski left a comment

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!

nwidynski Mar 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!

devongovett left a comment

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!

nwidynski Mar 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!

nwidynski commented Mar 14, 2026

Uh oh!

snowystinger commented Mar 14, 2026

Uh oh!

nwidynski commented Mar 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nwidynski commented Jul 12, 2025 •

edited

Loading

nwidynski Jul 25, 2025 •

edited

Loading

nwidynski Jul 27, 2025 •

edited

Loading

nwidynski Mar 14, 2026 •

edited

Loading

nwidynski Mar 14, 2026 •

edited

Loading