docs: Add docs for horizontal orientation by LFDanLu · Pull Request #9843 · adobe/react-spectrum

LFDanLu · 2026-03-25T22:08:27Z

Part of audit

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

Check out the docs updates

🧢 Your Project:

RSP

…entation

rspbot · 2026-03-25T22:15:25Z

Build successful! 🎉

LFDanLu · 2026-03-25T22:15:30Z

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

  constructor(options: ListLayoutOptions = {}) {
    super();
-    this.rowHeight = options.rowHeight ?? null;
+    this.rowHeight = options?.rowSize ?? options?.rowHeight ?? null;


We could also go ahead and change these height properties to be size as well, would just need to make it back compat with additional getters. Not sure if worth it if those would stick around for quite some time, but might reduce confusion

snowystinger · 2026-03-25T23:18:02Z

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

-    this.headingHeight = options.headingHeight ?? null;
-    this.estimatedHeadingHeight = options.estimatedHeadingHeight ?? null;
-    this.loaderHeight = options.loaderHeight ?? null;
+    this.estimatedRowHeight = options?.estimatedRowSize ?? options?.estimatedRowHeight ?? null;


did we want to change all the internal variables to size as well?

o, i think that's what you were saying here #9843 (comment)

yep, thats right. I might try and do it to see how bad it is

Btw, when working on this I was kind of unsure whether to use "size" here, since that typically refers to a 2-dimensional value in the context of our virtualizer package. I think it's fine, but wanted to share it for consideration - naming is hard 😅

haha yeah, I had a similar thought but couldn't think up of a better alternative either. I'll see about pushing up the full changes and then see if we can land on a better name

snowystinger · 2026-03-25T23:20:12Z

starters/docs/src/GridList.css

    grid-template-columns: auto;
    align-items: center;
+
+    &[data-orientation=horizontal] {


Need this in the tailwind starter as well

snowystinger · 2026-03-25T23:23:15Z

packages/dev/s2-docs/pages/react-aria/Virtualizer.mdx

+    selectionMode="multiple"
+    items={items}
+    style={{display: 'block', padding: 0, height: 100}}>
+    {(item) => <ListBoxItem style={{height: '100%'}}>{item.name}</ListBoxItem>}


We should add some styles to the items so that it's clear where one ends and the next begins. Right now it just looks like a long string of text with some random break in it.

It'd also be nice if this was an example I'd want to use, so if we can make them basically more like cards with a title and description, that'd be better

yihuiliao · 2026-03-26T17:57:36Z

packages/dev/s2-docs/pages/react-aria/Virtualizer.mdx

 ### List

-`ListLayout` supports layout of items in a vertical stack. Rows can be fixed or variable height. When using variable heights, set the `estimatedRowHeight` to a reasonable guess for how tall the rows will be on average. This allows the size of the scrollbar to be calculated.
+`ListLayout` places items along its orientation. Rows can be fixed or variable size. When using variable size, set the `estimatedRowSize` to a reasonable guess for how tall or wide the rows will be on average. This allows the size of the scrollbar to be calculated.


Suggested change

`ListLayout` places items along its orientation. Rows can be fixed or variable size. When using variable size, set the `estimatedRowSize` to a reasonable guess for how tall or wide the rows will be on average. This allows the size of the scrollbar to be calculated.

`ListLayout` places items along its orientation. Rows can be fixed or variable in size. When using a variable size, set the `estimatedRowSize` to a reasonable guess for how tall or wide the rows will be on average. This allows the size of the scrollbar to be calculated.

rspbot · 2026-03-26T18:43:08Z

Build successful! 🎉

yihuiliao · 2026-03-26T18:50:17Z

packages/dev/s2-docs/pages/react-aria/Virtualizer.mdx

+
+Use the `orientation` option to arrange items horizontally or vertically. Provide the same `orientation` on the collection component so keyboard navigation matches the layout.
+
+```tsx render docs={docs.exports.ListLayoutOptions} links={docs.links} props={['gap', 'padding']} initialProps={{estimatedRowSize: 300, gap: 8, padding: 8, orientation: 'horizontal'}} propsObject="layoutOptions" wide


any chance we make the images a tad bit smaller

rspbot · 2026-03-26T23:16:36Z

Build successful! 🎉

rspbot · 2026-03-26T23:16:38Z

## API Changes

react-aria-components

/react-aria-components:TableLayout

 TableLayout <O extends TableLayoutProps = TableLayoutProps, T> {
-  constructor: (ListLayoutOptions) => void
+  constructor: (TableLayoutProps) => void
   getContentSize: () => Size
   getDropTargetFromPoint: (number, number, (DropTarget) => boolean) => DropTarget | null
   getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
   getLayoutInfo: (Key) => LayoutInfo | null
   shouldInvalidate: (Rect, Rect) => boolean
   shouldInvalidateLayoutOptions: (TableLayoutProps, TableLayoutProps) => boolean
   update: (InvalidationContext<TableLayoutProps>) => void
   updateItemSize: (Key, Size) => boolean
   useLayoutOptions: () => TableLayoutProps
   virtualizer: Virtualizer<{}, any> | null
 }

/react-aria-components:ListLayoutOptions

 ListLayoutOptions {
   dropIndicatorThickness?: number = 2
-  estimatedHeadingHeight?: number
-  estimatedRowHeight?: number
+  estimatedHeadingSize?: number
+  estimatedRowSize?: number
   gap?: number = 0
-  headingHeight?: number = 48
-  loaderHeight?: number = 48
+  headingSize?: number = 48
+  loaderSize?: number = 48
   orientation?: Orientation = 'vertical'
   padding?: number = 0
-  rowHeight?: number = 48
+  rowSize?: number = 48
 }

/react-aria-components:TableLayoutProps

+TableLayoutProps {
+  columnWidths?: Map<Key, number>
+  dropIndicatorThickness?: number = 2
+  estimatedHeadingHeight?: number
+  estimatedRowHeight?: number
+  gap?: number = 0
+  headingHeight?: number = 48
+  loaderHeight?: number = 48
+  padding?: number = 0
+  rowHeight?: number = 48
+}

@internationalized/date

/@internationalized/date:DateValue

-DateValue {
-  D: undefined
-}

@react-spectrum/s2

/@react-spectrum/s2:ListView

 ListView <T extends {}> {
   UNSAFE_className?: UnsafeClassName
   UNSAFE_style?: CSSProperties
   aria-describedby?: string
   aria-details?: string
   aria-label?: string
   aria-labelledby?: string
   autoFocus?: boolean | FocusStrategy
   children: ReactNode | ({}) => ReactNode
   defaultSelectedKeys?: 'all' | Iterable<Key>
   dependencies?: ReadonlyArray<any>
   disabledBehavior?: DisabledBehavior = "all"
   disabledKeys?: Iterable<Key>
   disallowEmptySelection?: boolean
   disallowTypeAhead?: boolean = false
   escapeKeyBehavior?: 'clearSelection' | 'none' = 'clearSelection'
   hideLinkOutIcon?: boolean
   id?: string
   isQuiet?: boolean
   items?: Iterable<T>
   loadingState?: LoadingState
   onAction?: (Key) => void
   onLoadMore?: () => void
   onSelectionChange?: (Selection) => void
-  orientation?: Orientation = 'vertical'
   overflowMode?: 'wrap' | 'truncate' = 'truncate'
   renderActionBar?: ('all' | Set<Key>) => ReactElement
   renderEmptyState?: (GridListRenderProps) => ReactNode
   selectedKeys?: 'all' | Iterable<Key>
   selectionStyle?: 'highlight' | 'checkbox' = 'checkbox'
   shouldSelectOnPressUp?: boolean
   slot?: string | null
   styles?: StylesPropWithHeight
 }

/@react-spectrum/s2:ListViewProps

 ListViewProps <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
   defaultSelectedKeys?: 'all' | Iterable<Key>
   dependencies?: ReadonlyArray<any>
   disabledBehavior?: DisabledBehavior = "all"
   disabledKeys?: Iterable<Key>
   disallowEmptySelection?: boolean
   disallowTypeAhead?: boolean = false
   escapeKeyBehavior?: 'clearSelection' | 'none' = 'clearSelection'
   hideLinkOutIcon?: boolean
   id?: string
   isQuiet?: boolean
   items?: Iterable<T>
   loadingState?: LoadingState
   onAction?: (Key) => void
   onLoadMore?: () => void
   onSelectionChange?: (Selection) => void
-  orientation?: Orientation = 'vertical'
   overflowMode?: 'wrap' | 'truncate' = 'truncate'
   renderActionBar?: ('all' | Set<Key>) => ReactElement
   renderEmptyState?: (GridListRenderProps) => ReactNode
   selectedKeys?: 'all' | Iterable<Key>
   selectionStyle?: 'highlight' | 'checkbox' = 'checkbox'
   shouldSelectOnPressUp?: boolean
   slot?: string | null
   styles?: StylesPropWithHeight
 }

@react-spectrum/toast

/@react-spectrum/toast:CloseFunction

-CloseFunction {
-  C: undefined
-}

@react-stately/data

/@react-stately/data:AsyncListLoadFunction

-AsyncListLoadFunction {
-  A: undefined
-}

/@react-stately/data:AsyncListLoadOptions

-AsyncListLoadOptions <C, T> {
-  cursor?: C
-  filterText?: string
-  items: Array<T>
-  loadingState?: LoadingState
-  selectedKeys: Selection
-  signal: AbortSignal
-  sortDescriptor?: SortDescriptor
-}

/@react-stately/data:AsyncListStateUpdate

-AsyncListStateUpdate <C, T> {
-  cursor?: C
-  filterText?: string
-  items: Iterable<T>
-  selectedKeys?: Iterable<Key>
-  sortDescriptor?: SortDescriptor
-}

@react-stately/layout

/@react-stately/layout:TableLayout

 TableLayout <O extends TableLayoutProps = TableLayoutProps, T> {
-  constructor: (ListLayoutOptions) => void
+  constructor: (TableLayoutProps) => void
   getContentSize: () => Size
   getDropTargetFromPoint: (number, number, (DropTarget) => boolean) => DropTarget | null
   getDropTargetLayoutInfo: (ItemDropTarget) => LayoutInfo
   getLayoutInfo: (Key) => LayoutInfo | null
   shouldInvalidate: (Rect, Rect) => boolean
   shouldInvalidateLayoutOptions: (TableLayoutProps, TableLayoutProps) => boolean
   update: (InvalidationContext<TableLayoutProps>) => void
   updateItemSize: (Key, Size) => boolean
   virtualizer: Virtualizer<{}, any> | null
 }

/@react-stately/layout:ListLayoutOptions

 ListLayoutOptions {
   dropIndicatorThickness?: number = 2
-  estimatedHeadingHeight?: number
-  estimatedRowHeight?: number
+  estimatedHeadingSize?: number
+  estimatedRowSize?: number
   gap?: number = 0
-  headingHeight?: number = 48
-  loaderHeight?: number = 48
+  headingSize?: number = 48
+  loaderSize?: number = 48
   orientation?: Orientation = 'vertical'
   padding?: number = 0
-  rowHeight?: number = 48
+  rowSize?: number = 48
 }

/@react-stately/layout:TableLayoutProps

 TableLayoutProps {
   columnWidths?: Map<Key, number>
   dropIndicatorThickness?: number = 2
   estimatedHeadingHeight?: number
   estimatedRowHeight?: number
   gap?: number = 0
   headingHeight?: number = 48
   loaderHeight?: number = 48
-  orientation?: Orientation = 'vertical'
   padding?: number = 0
   rowHeight?: number = 48
 }

snowystinger

smaller images in the cards would be nice, otherwise looks good

LFDanLu added 4 commits March 25, 2026 11:01

prevent orientation from being exposed in S2 for gridlist

f61d08e

add docs for gridlist orientation

01b5d84

update ListLayoutOptions to clearer names and document horizontal ori…

4a1bba0

…entation

make it a bit smaller

177c7fe

github-actions bot added RAC S2 labels Mar 25, 2026

LFDanLu commented Mar 25, 2026

View reviewed changes

snowystinger reviewed Mar 25, 2026

View reviewed changes

yihuiliao reviewed Mar 26, 2026

View reviewed changes

LFDanLu added 3 commits March 26, 2026 11:05

update virtualizer list example per review

cbfdd67

update gridlist for horizontal

f1250cb

forgot to remove

164706a

yihuiliao reviewed Mar 26, 2026

View reviewed changes

rename rowHeight and other height related properties

c020c54

snowystinger approved these changes Mar 27, 2026

View reviewed changes

	`ListLayout` places items along its orientation. Rows can be fixed or variable size. When using variable size, set the `estimatedRowSize` to a reasonable guess for how tall or wide the rows will be on average. This allows the size of the scrollbar to be calculated.
	`ListLayout` places items along its orientation. Rows can be fixed or variable in size. When using a variable size, set the `estimatedRowSize` to a reasonable guess for how tall or wide the rows will be on average. This allows the size of the scrollbar to be calculated.


		Use the `orientation` option to arrange items horizontally or vertically. Provide the same `orientation` on the collection component so keyboard navigation matches the layout.

		```tsx render docs={docs.exports.ListLayoutOptions} links={docs.links} props={['gap', 'padding']} initialProps={{estimatedRowSize: 300, gap: 8, padding: 8, orientation: 'horizontal'}} propsObject="layoutOptions" wide

Conversation

LFDanLu commented Mar 25, 2026

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

rspbot commented Mar 25, 2026

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!

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!

rspbot commented Mar 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Mar 26, 2026

Uh oh!

rspbot commented Mar 26, 2026

react-aria-components

/react-aria-components:TableLayout

/react-aria-components:ListLayoutOptions

/react-aria-components:TableLayoutProps

@internationalized/date

/@internationalized/date:DateValue

@react-spectrum/s2

/@react-spectrum/s2:ListView

/@react-spectrum/s2:ListViewProps

@react-spectrum/toast

/@react-spectrum/toast:CloseFunction

@react-stately/data

/@react-stately/data:AsyncListLoadFunction

/@react-stately/data:AsyncListLoadOptions

/@react-stately/data:AsyncListStateUpdate

@react-stately/layout

/@react-stately/layout:TableLayout

/@react-stately/layout:ListLayoutOptions

/@react-stately/layout:TableLayoutProps

Uh oh!

snowystinger left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants