feat: support sections and headers in RAC gridlist (#8667)

yihuiliao · web-flow · commit 0df71d900606 · 2025-08-18T17:04:32.000Z
* initialize gridlist section and headers

* add test for gridlist sections

* add tests, cleanup

* fix lint

* remove spacing

* merge props, useLabels

* follow-up

* fix aria-rowindex

* remove aria-rolindex for headers

* pass state and ref to hook

* fix lint
diff --git a/packages/@react-aria/gridlist/src/index.ts b/packages/@react-aria/gridlist/src/index.ts
@@ -13,6 +13,7 @@
 export {useGridList} from './useGridList';
 export {useGridListItem} from './useGridListItem';
 export {useGridListSelectionCheckbox} from './useGridListSelectionCheckbox';
+export {useGridListSection} from './useGridListSection';
 
 export type {AriaGridListOptions, AriaGridListProps, GridListAria, GridListProps} from './useGridList';
 export type {AriaGridListItemOptions, GridListItemAria} from './useGridListItem';
diff --git a/packages/@react-aria/gridlist/src/useGridListItem.ts b/packages/@react-aria/gridlist/src/useGridListItem.ts
@@ -291,7 +291,10 @@ export function useGridListItem<T>(props: AriaGridListItemOptions, state: ListSt
   });
 
   if (isVirtualized) {
-    rowProps['aria-rowindex'] = node.index + 1;
+    let {collection} = state;
+    let nodes = [...collection];
+    // TODO: refactor ListCollection to store an absolute index of a node's position?
+    rowProps['aria-rowindex'] = nodes.find(node => node.type === 'section') ? [...collection.getKeys()].filter((key) => collection.getItem(key)?.type !== 'section').findIndex((key) => key === node.key) + 1 : node.index + 1;
   }
 
   let gridCellProps = {
diff --git a/packages/@react-aria/gridlist/src/useGridListSection.ts b/packages/@react-aria/gridlist/src/useGridListSection.ts
@@ -0,0 +1,60 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {DOMAttributes, RefObject} from '@react-types/shared';
+import type {ListState} from '@react-stately/list';
+import {useLabels, useSlotId} from '@react-aria/utils';
+
+export interface AriaGridListSectionProps {
+  /** An accessibility label for the section. Required if `heading` is not present. */
+  'aria-label'?: string
+}
+
+export interface GridListSectionAria {
+  /** Props for the wrapper list item. */
+  rowProps: DOMAttributes,
+
+  /** Props for the heading element, if any. */
+  rowHeaderProps: DOMAttributes,
+
+  /** Props for the grid's row group element. */
+  rowGroupProps: DOMAttributes
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a section in a grid list.
+ * See `useGridList` for more details about grid list.
+ * @param props - Props for the section.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export function useGridListSection<T>(props: AriaGridListSectionProps, state: ListState<T>, ref: RefObject<HTMLElement | null>): GridListSectionAria {
+  let {'aria-label': ariaLabel} = props;
+  let headingId = useSlotId();
+  let labelProps = useLabels({
+    'aria-label': ariaLabel,
+    'aria-labelledby': headingId
+  });
+
+  return {
+    rowProps: {
+      role: 'row'
+    },
+    rowHeaderProps: {
+      id: headingId,
+      role: 'rowheader'
+    },
+    rowGroupProps: {
+      role: 'rowgroup',
+      ...labelProps
+    }
+  };
+}
diff --git a/packages/react-aria-components/src/GridList.tsx b/packages/react-aria-components/src/GridList.tsx
@@ -9,17 +9,18 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
-import {AriaGridListProps, DraggableItemResult, DragPreviewRenderer, DropIndicatorAria, DroppableCollectionResult, FocusScope, ListKeyboardDelegate, mergeProps, useCollator, useFocusRing, useGridList, useGridListItem, useGridListSelectionCheckbox, useHover, useLocale, useVisuallyHidden} from 'react-aria';
+import {AriaGridListProps, DraggableItemResult, DragPreviewRenderer, DropIndicatorAria, DroppableCollectionResult, FocusScope, ListKeyboardDelegate, mergeProps, useCollator, useFocusRing, useGridList, useGridListItem, useGridListSection, useGridListSelectionCheckbox, useHover, useLocale, useVisuallyHidden} from 'react-aria';
 import {ButtonContext} from './Button';
 import {CheckboxContext} from './RSPContexts';
-import {Collection, CollectionBuilder, createLeafComponent} from '@react-aria/collections';
-import {CollectionProps, CollectionRendererContext, DefaultCollectionRenderer, ItemRenderProps} from './Collection';
+import {Collection, CollectionBuilder, createBranchComponent, createLeafComponent} from '@react-aria/collections';
+import {CollectionProps, CollectionRendererContext, DefaultCollectionRenderer, ItemRenderProps, SectionProps} from './Collection';
 import {ContextValue, DEFAULT_SLOT, Provider, RenderProps, SlotProps, StyleProps, StyleRenderProps, useContextProps, useRenderProps} from './utils';
 import {DragAndDropContext, DropIndicatorContext, DropIndicatorProps, useDndPersistedKeys, useRenderDropIndicator} from './DragAndDrop';
 import {DragAndDropHooks} from './useDragAndDrop';
 import {DraggableCollectionState, DroppableCollectionState, Collection as ICollection, ListState, Node, SelectionBehavior, useListState} from 'react-stately';
 import {filterDOMProps, inertValue, LoadMoreSentinelProps, useLoadMoreSentinel, useObjectRef} from '@react-aria/utils';
 import {forwardRefType, GlobalDOMAttributes, HoverEvents, Key, LinkDOMProps, PressEvents, RefObject} from '@react-types/shared';
+import {HeaderContext} from './Header';
 import {ListStateContext} from './ListBox';
 import React, {createContext, ForwardedRef, forwardRef, HTMLAttributes, JSX, ReactNode, useContext, useEffect, useMemo, useRef} from 'react';
 import {TextContext} from './Text';
@@ -561,3 +562,58 @@ export const GridListLoadMoreItem = createLeafComponent('loader', function GridL
     </>
   );
 });
+
+export interface GridListSectionProps<T> extends SectionProps<T> {}
+
+/**
+ * A GridListSection represents a section within a GridList.
+ */
+export const GridListSection = /*#__PURE__*/ createBranchComponent('section', <T extends object>(props: GridListSectionProps<T>, ref: ForwardedRef<HTMLElement>, item: Node<T>) => {
+  let state = useContext(ListStateContext)!;
+  let {CollectionBranch} = useContext(CollectionRendererContext);
+  let headingRef = useRef(null);
+  ref = useObjectRef<HTMLElement>(ref);
+  let {rowHeaderProps, rowProps, rowGroupProps} = useGridListSection({
+    'aria-label': props['aria-label'] ?? undefined
+  }, state, ref);
+  let renderProps = useRenderProps({
+    defaultClassName: 'react-aria-GridListSection',
+    className: props.className,
+    style: props.style,
+    values: {}
+  });
+
+  let DOMProps = filterDOMProps(props as any, {global: true});
+  delete DOMProps.id;
+
+  return (
+    <section
+      {...mergeProps(DOMProps, renderProps, rowGroupProps)}
+      ref={ref}>
+      <Provider
+        values={[
+          [HeaderContext, {...rowProps, ref: headingRef}],
+          [GridListHeaderContext, {...rowHeaderProps}]
+        ]}>
+        <CollectionBranch
+          collection={state.collection}
+          parent={item} />
+      </Provider>
+    </section>
+  );
+});
+
+const GridListHeaderContext = createContext<HTMLAttributes<HTMLElement> | null>(null);
+
+export const GridListHeader = /*#__PURE__*/ createLeafComponent('header', function Header(props: HTMLAttributes<HTMLElement>, ref: ForwardedRef<HTMLElement>) {
+  [props, ref] = useContextProps(props, ref, HeaderContext);
+  let rowHeaderProps = useContext(GridListHeaderContext);
+
+  return (
+    <header {...props} ref={ref}>
+      <div {...rowHeaderProps} style={{display: 'contents'}}>
+        {props.children}
+      </div>
+    </header>
+  );
+});
diff --git a/packages/react-aria-components/src/index.ts b/packages/react-aria-components/src/index.ts
@@ -39,7 +39,7 @@ export {DropZone, DropZoneContext} from './DropZone';
 export {FieldError, FieldErrorContext} from './FieldError';
 export {FileTrigger} from './FileTrigger';
 export {Form, FormContext} from './Form';
-export {GridListLoadMoreItem, GridList, GridListItem, GridListContext} from './GridList';
+export {GridListLoadMoreItem, GridList, GridListItem, GridListContext, GridListHeader, GridListSection} from './GridList';
 export {Group, GroupContext} from './Group';
 export {Header, HeaderContext} from './Header';
 export {Heading} from './Heading';
diff --git a/packages/react-aria-components/stories/GridList.stories.tsx b/packages/react-aria-components/stories/GridList.stories.tsx
@@ -21,10 +21,12 @@ import {
   DropIndicator,
   GridLayout,
   GridList,
+  GridListHeader,
   GridListItem,
   GridListItemProps,
   GridListLoadMoreItem,
   GridListProps,
+  GridListSection,
   Heading,
   ListLayout,
   Modal,
@@ -145,6 +147,105 @@ const MyCheckbox = ({children, ...props}: CheckboxProps) => {
   );
 };
 
+
+export const GridListSectionExample = (args) => (
+  <GridList
+    {...args}
+    className={styles.menu}
+    aria-label="test gridlist"
+    style={{
+      width: 400,
+      height: 400
+    }}>
+    <GridListSection>
+      <GridListHeader>Section 1</GridListHeader>
+      <MyGridListItem>1,1 <Button>Actions</Button></MyGridListItem>
+      <MyGridListItem>1,2 <Button>Actions</Button></MyGridListItem>
+      <MyGridListItem>1,3 <Button>Actions</Button></MyGridListItem>
+    </GridListSection>
+    <GridListSection>
+      <GridListHeader>Section 2</GridListHeader>
+      <MyGridListItem>2,1 <Button>Actions</Button></MyGridListItem>
+      <MyGridListItem>2,2 <Button>Actions</Button></MyGridListItem>
+      <MyGridListItem>2,3 <Button>Actions</Button></MyGridListItem>
+    </GridListSection>
+    <GridListSection>
+      <GridListHeader>Section 3</GridListHeader>
+      <MyGridListItem>3,1 <Button>Actions</Button></MyGridListItem>
+      <MyGridListItem>3,2 <Button>Actions</Button></MyGridListItem>
+      <MyGridListItem>3,3 <Button>Actions</Button></MyGridListItem>
+    </GridListSection>
+  </GridList>
+);
+
+GridListSectionExample.story = {
+  args: {
+    layout: 'stack',
+    escapeKeyBehavior: 'clearSelection',
+    shouldSelectOnPressUp: false
+  },
+  argTypes: {
+    layout: {
+      control: 'radio',
+      options: ['stack', 'grid']
+    },
+    keyboardNavigationBehavior: {
+      control: 'radio',
+      options: ['arrow', 'tab']
+    },
+    selectionMode: {
+      control: 'radio',
+      options: ['none', 'single', 'multiple']
+    },
+    selectionBehavior: {
+      control: 'radio',
+      options: ['toggle', 'replace']
+    },
+    escapeKeyBehavior: {
+      control: 'radio',
+      options: ['clearSelection', 'none']
+    }
+  }
+};
+
+export function VirtualizedGridListSection() {
+  let sections: {id: string, name: string, children: {id: string, name: string}[]}[] = [];
+  for (let s = 0; s < 10; s++) {
+    let items: {id: string, name: string}[] = [];
+    for (let i = 0; i < 3; i++) {
+      items.push({id: `item_${s}_${i}`, name: `Section ${s}, Item ${i}`});
+    }
+    sections.push({id: `section_${s}`, name: `Section ${s}`, children: items});
+  }
+
+  return (
+    <Virtualizer
+      layout={ListLayout}
+      layoutOptions={{
+        rowHeight: 25
+      }}>
+      <GridList
+        className={styles.menu}
+        // selectionMode="multiple"
+        style={{height: 400}}
+        aria-label="virtualized with grid section"
+        items={sections}>
+        <Collection items={sections}>
+          {section => (
+            <GridListSection>
+              <GridListHeader>{section.name}</GridListHeader>
+              <Collection items={section.children} >
+                {item => <MyGridListItem>{item.name}</MyGridListItem>}
+              </Collection>
+            </GridListSection>
+          )}
+        </Collection>
+      </GridList>
+    </Virtualizer>
+  );
+}
+
+
 const VirtualizedGridListRender = (args: GridListProps<any> & {isLoading: boolean}) => {
   let items: {id: number, name: string}[] = [];
   for (let i = 0; i < 10000; i++) {
diff --git a/packages/react-aria-components/test/GridList.test.js b/packages/react-aria-components/test/GridList.test.js
@@ -20,7 +20,9 @@ import {
   DropIndicator,
   GridList,
   GridListContext,
+  GridListHeader,
   GridListItem,
+  GridListSection,
   Label,
   ListLayout,
   Modal,
@@ -45,6 +47,23 @@ let TestGridList = ({listBoxProps, itemProps}) => (
   </GridList>
 );
 
+let TestGridListSections = ({listBoxProps, itemProps}) => (
+  <GridList aria-label="Test" {...listBoxProps}>
+    <GridListSection>
+      <GridListHeader>Favorite Animal</GridListHeader>
+      <GridListItem {...itemProps} id="cat" textValue="Cat"><Checkbox slot="selection" /> Cat</GridListItem>
+      <GridListItem {...itemProps} id="dog" textValue="Dog"><Checkbox slot="selection" /> Dog</GridListItem>
+      <GridListItem {...itemProps} id="kangaroo" textValue="Kangaroo"><Checkbox slot="selection" /> Kangaroo</GridListItem>
+    </GridListSection>
+    <GridListSection aria-label="Favorite Ice Cream">
+      <GridListItem {...itemProps} id="cat" textValue="Vanilla"><Checkbox slot="selection" />Vanilla</GridListItem>
+      <GridListItem {...itemProps} id="dog" textValue="Chocolate"><Checkbox slot="selection" />Chocolate</GridListItem>
+      <GridListItem {...itemProps} id="kangaroo" textValue="Strawberry"><Checkbox slot="selection" />Strawberry</GridListItem>
+    </GridListSection>
+  </GridList>
+);
+
+
 let DraggableGridList = (props) => {
   let {dragAndDropHooks} = useDragAndDrop({
     getItems: (keys) => [...keys].map((key) => ({'text/plain': key})),
@@ -413,6 +432,68 @@ describe('GridList', () => {
     expect(items[2]).toHaveAttribute('aria-selected', 'true');
   });
 
+  it('should support sections', () => {
+    let {getAllByRole} = render(<TestGridListSections />);
+
+    let groups = getAllByRole('rowgroup');
+    expect(groups).toHaveLength(2);
+
+    expect(groups[0]).toHaveClass('react-aria-GridListSection');
+    expect(groups[1]).toHaveClass('react-aria-GridListSection');
+
+    expect(groups[0]).toHaveAttribute('aria-labelledby');
+    expect(document.getElementById(groups[0].getAttribute('aria-labelledby'))).toHaveTextContent('Favorite Animal');
+    expect(groups[1].getAttribute('aria-label')).toEqual('Favorite Ice Cream');
+  });
+
+  it('should update collection when moving item to a different section', () => {
+    let {getAllByRole, rerender} = render(
+      <GridList aria-label="Test">
+        <GridListSection id="veggies">
+          <GridListHeader>Veggies</GridListHeader>
+          <GridListItem key="lettuce" id="lettuce">Lettuce</GridListItem>
+          <GridListItem key="tomato" id="tomato">Tomato</GridListItem>
+          <GridListItem key="onion" id="onion">Onion</GridListItem>
+        </GridListSection>
+        <GridListSection id="meats">
+          <GridListHeader>Meats</GridListHeader>
+          <GridListItem key="ham" id="ham">Ham</GridListItem>
+          <GridListItem key="tuna" id="tuna">Tuna</GridListItem>
+          <GridListItem key="tofu" id="tofu">Tofu</GridListItem>
+        </GridListSection>
+      </GridList>
+    );
+
+    let sections = getAllByRole('rowgroup');
+    let items = within(sections[0]).getAllByRole('gridcell');
+    expect(items).toHaveLength(3);
+    items = within(sections[1]).getAllByRole('gridcell');
+    expect(items).toHaveLength(3);
+
+    rerender(
+      <GridList aria-label="Test">
+        <GridListSection id="veggies">
+          <GridListHeader>Veggies</GridListHeader>
+          <GridListItem key="lettuce" id="lettuce">Lettuce</GridListItem>
+          <GridListItem key="tomato" id="tomato">Tomato</GridListItem>
+          <GridListItem key="onion" id="onion">Onion</GridListItem>
+          <GridListItem key="ham" id="ham">Ham</GridListItem>
+        </GridListSection>
+        <GridListSection id="meats">
+          <GridListHeader>Meats</GridListHeader>
+          <GridListItem key="tuna" id="tuna">Tuna</GridListItem>
+          <GridListItem key="tofu" id="tofu">Tofu</GridListItem>
+        </GridListSection>
+      </GridList>
+    );
+
+    sections = getAllByRole('rowgroup');
+    items = within(sections[0]).getAllByRole('gridcell');
+    expect(items).toHaveLength(4);
+    items = within(sections[1]).getAllByRole('gridcell');
+    expect(items).toHaveLength(2);
+  });
+
   describe('selectionBehavior="replace"', () => {
     // Required for proper touch detection
     installPointerEvent();
diff --git a/packages/react-aria/src/index.ts b/packages/react-aria/src/index.ts
