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

nwidynski · 2025-07-12T00:31:40Z

This PR adds support for horizontal orientations to ListLayout and affected components in preparation for a Carousel contribution.

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

…to layout-orientation

…ayout-orientation

nwidynski · 2025-07-12T00:39:17Z

@LFDanLu Would you be so kind to issue a build for this PR? I'm going insane because of a bug with virtualized dnd, which I can't seem to get rid of locally, even after reverting all changes and clearing caches. I would really like to know whether the issue exists on remote 😅

nwidynski · 2025-07-12T01:38:55Z

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


-  constructor(ref: RefObject<HTMLElement | null>) {
+  constructor(ref: RefObject<HTMLElement | null>, orientation?: Orientation) {


Not entirely happy with having to pass this here, but I couldn't think of any reliable alternative. I guess we could do something similar to the drop target delegate and place this information in a data attribute, but is this really preferable?

Yeah I'd rather not rely on a data attribute for this, this is fine for now IMO. Having the aria roles and their orientations here in the delegate is interesting, wonder if it would make sense to instead only rely on the higher level delegate (and by extension the hook that creates the keyboard delegate) to pass the appropriate orientation. I guess this makes for a good fallback as is though

Chatted with the team some more about this, and we wondered if we really need have the orientation information here in the DOMLayoutDelegate since this delegate is mainly meant to inform about stuff like itemRects and sizes. What was the need for this information to be placed here since the keyboard delegates already were passed orientation via their options?

Are you asking about why the LayoutDelegate interface in general requires an orientation or rather about DOMLayoutDelegate specifically? If the later, then as you speculated it's just meant to provide reasonable fallback in case the keyboard delegate is not passed an orientation - can remove if you prefer.

In case you are wondering why we expose a getOrientation() method instead of keeping this option protected in the layout, its because we can utilize this method to provide a fallback in the keyboard delegates and therefore make the orientation prop on the hook optional. This way a user doesn't have to set orientation=horizontal both in the layout options and on the component.

mainly was concerned about the DOMLayoutDelegate, but was wondering if a fallback was really needed. I was imagining that the orientation would be passed from the component level if customizable or have its default set by the respective hook and passed to the delegate, though I do see your point about then needing the user to provide it to the Virtualizer's layout as well.

Yeah, I felt like it would be fairly easy for a user to miss the orientation on the component and just set it in the layout since it will already look right, just wont be working correctly for keyboard users. Having it that way ensures we are in sync, especially with the discussed warning message.

nwidynski · 2025-07-14T20:39:11Z

packages/@react-aria/combobox/src/useComboBox.ts

@@ -380,6 +381,7 @@ export function useComboBox<T>(props: AriaComboBoxOptions<T>, state: ComboBoxSta
      shouldUseVirtualFocus: true,
      shouldSelectOnPressUp: true,
      shouldFocusOnHover: true,
+      orientation: 'vertical' as const,


We should explicitly set orientation whenever known to avoid queries to the DOMLayoutDelegate internally.

nwidynski · 2025-07-14T20:41:03Z

packages/@react-aria/listbox/src/useListBox.ts

@@ -117,6 +123,7 @@ export function useListBox<T>(props: AriaListBoxOptions<T>, state: ListState<T>,
      'aria-multiselectable': 'true'
    } : {}, {
      role: 'listbox',
+      'aria-orientation': orientation === 'horizontal' ? orientation : undefined,


@majornista Should we set aria-orientation only if deviating from the implicit orientation as defined in each role spec? I adjusted useTabList as well to match, let me know what you think 🙏

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

LFDanLu · 2025-07-14T23:10:33Z

@nwidynski heya sorry about the delay, opened #8544 for your build

nwidynski · 2025-07-14T23:32:07Z

@LFDanLu Thanks! I will take a look tmrw, otherwise this is ready for review if the team finds time 👍

LFDanLu · 2025-07-15T00:10:30Z

sounds good, we are gearing up for a release very soon, but noted this one down (and #8523) for the team to checkout right after!

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

LFDanLu

Will be bring this up with the team tomorrow, but looks good to me at a glance, thanks!

LFDanLu · 2025-07-23T23:30:41Z

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


-  constructor(ref: RefObject<HTMLElement | null>) {
+  constructor(ref: RefObject<HTMLElement | null>, orientation?: Orientation) {


Yeah I'd rather not rely on a data attribute for this, this is fine for now IMO. Having the aria roles and their orientations here in the delegate is interesting, wonder if it would make sense to instead only rely on the higher level delegate (and by extension the hook that creates the keyboard delegate) to pass the appropriate orientation. I guess this makes for a good fallback as is though

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

LFDanLu · 2025-07-23T23:33:14Z

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

+    // TODO: Should we log a warning if keyboard and layout delegate mismatch in orientation?
+    return this.orientation || this.layoutDelegate.getOrientation?.() || 'vertical';


I think it makes sense to log a dev mode only warning here, save some pain down the line haha

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

LFDanLu · 2025-07-24T22:52:19Z

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


-  constructor(ref: RefObject<HTMLElement | null>) {
+  constructor(ref: RefObject<HTMLElement | null>, orientation?: Orientation) {


Chatted with the team some more about this, and we wondered if we really need have the orientation information here in the DOMLayoutDelegate since this delegate is mainly meant to inform about stuff like itemRects and sizes. What was the need for this information to be placed here since the keyboard delegates already were passed orientation via their options?

packages/@react-stately/virtualizer/src/OverscanManager.ts

LFDanLu · 2025-07-24T23:03:58Z

mainly wondering if some of the changes/refactors can be simplified since we already supported orientation for Listbox previously

nwidynski · 2025-07-24T23:37:39Z

@LFDanLu Maybe the PR title is misleading - The primary target of this is to add orientation to the Layout class and its derivates, e.g. ListLayout. While the Listbox did support orientation, it was only affecting keyboard movement and not visual layout for virtualization.

…to layout-orientation

nwidynski added 4 commits July 12, 2025 00:57

feat: add orientation to layout

b07954a

Merge branch 'main' of https://github.com/nwidynski/react-spectrum in…

ef61fa4

…to layout-orientation

feat: forward orientation to gridlist keyboard delegate

36ad8c4

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

bc57b0c

…ayout-orientation

nwidynski mentioned this pull request Jul 12, 2025

feat: Add CollectionNode to collection renderer #8523

Open

5 tasks

nwidynski commented Jul 12, 2025

View reviewed changes

nwidynski added 2 commits July 12, 2025 17:51

fix: remove duplicate keyboard delegate in gridlist

e92c7db

Feat: Add support for orientation to KeyboardDelegate interface

58ad7a2

nwidynski changed the title ~~Feat: Add support for horizontal orientation to ListLayout delegate~~ Feat: Add support for horizontal orientation to GridList & ListBox Jul 14, 2025

nwidynski commented Jul 14, 2025

View reviewed changes

fix: implement layout delegate interface

22ddea9

nwidynski commented Jul 14, 2025

View reviewed changes

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

nwidynski commented Jul 21, 2025

View reviewed changes

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

fix: enumerable keys

2d97559

LFDanLu reviewed Jul 23, 2025

View reviewed changes

LFDanLu reviewed Jul 24, 2025

View reviewed changes

nwidynski force-pushed the layout-orientation branch from b6452fc to 2d97559 Compare July 25, 2025 09:56

nwidynski added 2 commits July 25, 2025 19:30

Merge branch 'main' of https://github.com/nwidynski/react-spectrum in…

ecd054d

…to layout-orientation

fix: bidirectional overscan for table layout

d6a8401


		constructor(ref: RefObject<HTMLElement \| null>) {
		constructor(ref: RefObject<HTMLElement \| null>, orientation?: Orientation) {

		// TODO: Should we log a warning if keyboard and layout delegate mismatch in orientation?
		return this.orientation \|\| this.layoutDelegate.getOrientation?.() \|\| 'vertical';

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

Are you sure you want to change the base?

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

Conversation

nwidynski commented Jul 12, 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!

nwidynski commented Jul 12, 2025

Uh oh!

nwidynski Jul 12, 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!

LFDanLu Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

LFDanLu Jul 24, 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 24, 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!

LFDanLu Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

nwidynski Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

nwidynski Jul 14, 2025

Choose a reason for hiding this comment

Uh oh!

nwidynski Jul 14, 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!

Uh oh!

LFDanLu commented Jul 14, 2025

Uh oh!

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

Uh oh!

Uh oh!

LFDanLu commented Jul 15, 2025

Uh oh!

Uh oh!

LFDanLu left a comment

Choose a reason for hiding this comment

Uh oh!

LFDanLu Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

LFDanLu Jul 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

LFDanLu Jul 24, 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!

Uh oh!

LFDanLu commented Jul 24, 2025

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

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

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

nwidynski commented Jul 12, 2025 •

edited

Loading

nwidynski Jul 12, 2025 •

edited

Loading

LFDanLu Jul 24, 2025 •

edited

Loading

nwidynski Jul 24, 2025 •

edited

Loading

nwidynski Jul 14, 2025 •

edited

Loading

nwidynski commented Jul 14, 2025 •

edited

Loading

LFDanLu Jul 24, 2025 •

edited

Loading

nwidynski commented Jul 24, 2025 •

edited

Loading