feat: support sections and headers in RAC gridlist #8667

yihuiliao · 2025-08-01T23:51:34Z

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 using the two added stories in RAC. one is virtualized + dynamic, the other is non-virtualized static

🧢 Your Project:

rspbot · 2025-08-01T23:58:26Z

Build successful! 🎉

rspbot · 2025-08-02T00:00:39Z

Build successful! 🎉

snowystinger · 2025-08-05T00:05:08Z

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

+ * See `useGridList` for more details about grid list.
+ * @param props - Props for the section.
+ */
+export function useGridListSection(props: AriaGridListSectionProps): GridListSectionAria {


pass state and ref, we always seem to regret not passing them and it's breaking to add them later

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

snowystinger · 2025-08-05T00:07:53Z

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

@@ -245,7 +246,8 @@ function GridListInner<T extends object>({props, collection, gridListRef: ref}:
          values={[
            [ListStateContext, state],
            [DragAndDropContext, {dragAndDropHooks, dragState, dropState}],
-            [DropIndicatorContext, {render: GridListDropIndicatorWrapper}]
+            [DropIndicatorContext, {render: GridListDropIndicatorWrapper}],
+            [SectionContext, {name: 'GridListSection', render: GridListSectionInner}]


what's this name for?

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

snowystinger · 2025-08-05T00:33:15Z

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

+
+const GridListHeaderContext = createContext<HTMLAttributes<HTMLElement> | null>(null);
+
+export const GridListHeader = /*#__PURE__*/ createLeafComponent('header', function Header(props: HTMLAttributes<HTMLElement>, ref: ForwardedRef<HTMLElement>) {


do we need a special one for GridList? I assume it has to do with the extra row div? would it make more sense as two components instead?

It's a little weird because ordinarily the ref would attach to the outer most element. This also makes it hard to style the div since there's no classname on it

i guess we could do something like

<GridListHeader> <Header /> </GridListHeader>

where GridListHeader is just a div with the role='row'

but yeah, the reason is again for this was because the role=row-header as to be inside a div with a role=row

yihuiliao · 2025-08-04T23:57:51Z

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

+
+const GridListHeaderContext = createContext<HTMLAttributes<HTMLElement> | null>(null);
+
+export const GridListHeader = /*#__PURE__*/ createLeafComponent('header', function Header(props: HTMLAttributes<HTMLElement>, ref: ForwardedRef<HTMLElement>) {


with ListBox, you can just use a normal Header, but with GridList, in order to follow correct aria-pattern, the header must be inside a div with a role=row, hence why i've created a new component called GridListHeader. are we okay with that?

from WAI-ARIA:

Each cell is either a DOM descendant of or owned by a row element and has one of the following roles:

columnheader if the cell contains a title or header information for the column.

rowheader if the cell contains title or header information for the row.

gridcell if the cell does not contain column or row header information.

I think this is ok, but the row itself should get aria-attributes like aria-rowindex when virtualized if so.

yihuiliao · 2025-08-05T16:41:21Z

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

+
+const GridListHeaderContext = createContext<HTMLAttributes<HTMLElement> | null>(null);
+
+export const GridListHeader = /*#__PURE__*/ createLeafComponent('header', function Header(props: HTMLAttributes<HTMLElement>, ref: ForwardedRef<HTMLElement>) {


i guess we could do something like

<GridListHeader> <Header /> </GridListHeader>

where GridListHeader is just a div with the role='row'

but yeah, the reason is again for this was because the role=row-header as to be inside a div with a role=row

rspbot · 2025-08-05T17:33:16Z

Build successful! 🎉

rspbot · 2025-08-05T17:33:18Z

## API Changes

react-aria-components

/react-aria-components:GridListHeader

+GridListHeader {
+  UNTYPED
+}

/react-aria-components:GridListSection

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

@react-aria/gridlist

/@react-aria/gridlist:useGridListSection

+useGridListSection {
+  props: AriaGridListSectionProps
+  returnVal: undefined
+}

@react-aria/i18n

/@react-aria/i18n:isRTL

-isRTL {
-  localeString: string
-  returnVal: undefined
-}

devongovett · 2025-08-05T23:59:45Z

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

+  rowProps: DOMAttributes,
+
+  /** Props for the heading element, if any. */
+  headingProps: DOMAttributes,


Can we make this rowHeaderProps to match the role?

devongovett · 2025-08-06T00:02:02Z

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

@@ -245,7 +246,8 @@ function GridListInner<T extends object>({props, collection, gridListRef: ref}:
          values={[
            [ListStateContext, state],
            [DragAndDropContext, {dragAndDropHooks, dragState, dropState}],
-            [DropIndicatorContext, {render: GridListDropIndicatorWrapper}]
+            [DropIndicatorContext, {render: GridListDropIndicatorWrapper}],
+            [SectionContext, {name: 'GridListSection', render: GridListSectionInner}]


We can remove this SectionContext. This is only for backward compatibility in ListBox/Menu from when we used to have only a single <Section>, but we don't need that here. You'll render a <GridListSection> directly, not a <Section>.

devongovett · 2025-08-06T00:02:56Z

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

+
+export interface GridListSectionProps<T> extends SectionProps<T> {}
+
+function GridListSectionInner<T extends object>(props: GridListSectionProps<T>, ref: ForwardedRef<HTMLElement>, section: Node<T>, className = 'react-aria-GridListSection') {


Based on above comment, you can merge this into GridListSection

devongovett · 2025-08-06T00:59:54Z

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

+
+  return (
+    <div {...rowProps} >
+      <header className="react-aria-Header" {...props} ref={ref}>


Having two elements will make this harder to style. Maybe we can use display: 'contents' on the inner one so we have the correct ARIA structure, but you only need to style the outer one:

<header {...rowProps} ref={ref}> <div {...rowHeaderProps} style={{display: 'contents'}}> {children} </div> </header>

This would match the structure of GridListItem too.

linking related discussion #8667 (comment)

I think I like the display contents better

+1, I did the same for the load more elements too (i.e. TableLoadMoreItem)

LFDanLu

still need to test the screenreader behavior but just some things I noted when scanning the code

LFDanLu · 2025-08-06T20:47:07Z

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

+ */
+export function useGridListSection(props: AriaGridListSectionProps): GridListSectionAria {
+  let {heading, 'aria-label': ariaLabel} = props;
+  let headingId = useId();


nit, but I wonder if we can omit passing the heading to the hook and instead leverage useSlotId to generate this headingId? That way either the user spreads headingProps onto an element and thus the id + aria-labelledby stick around or they don't and the id doesn't get used

LFDanLu · 2025-08-06T20:54:51Z

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

+
+const GridListHeaderContext = createContext<HTMLAttributes<HTMLElement> | null>(null);
+
+export const GridListHeader = /*#__PURE__*/ createLeafComponent('header', function Header(props: HTMLAttributes<HTMLElement>, ref: ForwardedRef<HTMLElement>) {


I think this is ok, but the row itself should get aria-attributes like aria-rowindex when virtualized if so.

yihuiliao added 5 commits July 22, 2025 16:52

initialize gridlist section and headers

13f30a4

add test for gridlist sections

42939bf

add tests, cleanup

1cec0c1

fix lint

72c57d3

remove spacing

56c400e

yihuiliao marked this pull request as ready for review August 5, 2025 00:01

yihuiliao added the ready for review label Aug 5, 2025

snowystinger reviewed Aug 5, 2025

View reviewed changes

yihuiliao commented Aug 5, 2025

View reviewed changes

merge props, useLabels

519e0c6

devongovett reviewed Aug 6, 2025

View reviewed changes

LFDanLu reviewed Aug 6, 2025

View reviewed changes


		const GridListHeaderContext = createContext<HTMLAttributes<HTMLElement> \| null>(null);

		export const GridListHeader = /#__PURE__/ createLeafComponent('header', function Header(props: HTMLAttributes<HTMLElement>, ref: ForwardedRef<HTMLElement>) {


		export interface GridListSectionProps<T> extends SectionProps<T> {}

		function GridListSectionInner<T extends object>(props: GridListSectionProps<T>, ref: ForwardedRef<HTMLElement>, section: Node<T>, className = 'react-aria-GridListSection') {

feat: support sections and headers in RAC gridlist #8667

Are you sure you want to change the base?

feat: support sections and headers in RAC gridlist #8667

Conversation

yihuiliao commented Aug 1, 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 Aug 1, 2025

Uh oh!

rspbot commented Aug 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

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 Aug 5, 2025

Uh oh!

rspbot commented Aug 5, 2025

react-aria-components

/react-aria-components:GridListHeader

/react-aria-components:GridListSection

@react-aria/gridlist

/@react-aria/gridlist:useGridListSection

@react-aria/i18n

/@react-aria/i18n:isRTL

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!

LFDanLu 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!

Uh oh!

yihuiliao commented Aug 1, 2025 •

edited

Loading