Skip to content

GridList

A grid list displays a list of interactive items, with support for keyboard navigation, single or multiple selection, and row actions.

Note: Use GridList when your list items may contain interactive elements such as buttons, checkboxes, menus, etc. within them. If your list items contain only static content such as text and images, then consider using ListBox instead for a slightly better screen reader experience (especially on mobile).

Import

import { GridList } from "@cfa/react-core";

Live Editor

Examples

Basic Usage

A GridList with selectable items. The component handles keyboard navigation, focus management, and accessibility automatically.

Multiple Selection with Checkboxes

You can enable multiple selection with checkboxes by setting the selectionMode to “multiple” and adding a Checkbox component with a slot="selection" prop.

Sections / Grouping

GridList supports using sections to group items. When using sections, it is preferred that you group all of the available options. Leaving some items as “ungrouped” can sometimes cause confusion.

With Interactive Elements

The GridList component can include interactive elements like buttons within each item. This example demonstrates how to add an IconButton to each item.

Props

Visit the Documentation Site for the full list of props.

NameTypeDefaultDescription
aria-describedbystring-Identifies the element (or elements) that describes the object.
aria-detailsstring-Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-labelstring-Defines a string value that labels the current element.
aria-labelledbystring-Identifies the element (or elements) that labels the current element.
autoFocusboolean | FocusStrategy-Whether to auto focus the gridlist or an option.
childrenReactNode | ((item: T) => ReactNode)-The contents of the collection.
classNameClassNameOrFunction<GridListRenderProps>'react-aria-GridList'The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.
defaultSelectedKeys"all" | Iterable<Key>-The initial selected keys in the collection (uncontrolled).
dependenciesreadonly any[]-Values that should invalidate the item cache when using dynamic collections.
dirstring--
disabledBehaviorDisabledBehavior"all"Whether `disabledKeys` applies to all interactions, or only selection.
disabledKeysIterable<Key>-The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
disallowEmptySelectionboolean-Whether the collection allows empty selection.
disallowTypeAheadbooleanfalseWhether typeahead navigation is disabled.
dragAndDropHooksDragAndDropHooks<NoInfer<T>>-The drag and drop hooks returned by `useDragAndDrop` used to enable drag and drop behavior for the GridList.
escapeKeyBehavior"clearSelection" | "none"'clearSelection'Whether pressing the escape key should clear selection in the grid list or not. Most experiences should not modify this option as it eliminates a keyboard user's ability to easily clear selection. Only use if the escape key is being handled externally or should not trigger selection clearing contextually.
hiddenboolean--
idstring-The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
inertboolean--
itemsIterable<T>-Item objects in the collection.
keyboardNavigationBehavior"arrow" | "tab"'arrow'Whether keyboard navigation to focusable elements within grid list items is via the left/right arrow keys or the tab key.
langstring--
layout"stack" | "grid"'stack'Whether the items are arranged in a stack or grid.
onAction(key: Key) => void-Handler that is called when a user performs an action on an item. The exact user event depends on the collection's `selectionBehavior` prop and the interaction modality.
onAnimationEndAnimationEventHandler<HTMLDivElement>--
onAnimationEndCaptureAnimationEventHandler<HTMLDivElement>--
onAnimationIterationAnimationEventHandler<HTMLDivElement>--
onAnimationIterationCaptureAnimationEventHandler<HTMLDivElement>--
onAnimationStartAnimationEventHandler<HTMLDivElement>--
onAnimationStartCaptureAnimationEventHandler<HTMLDivElement>--
onAuxClickMouseEventHandler<HTMLDivElement>--
onAuxClickCaptureMouseEventHandler<HTMLDivElement>--
onClickMouseEventHandler<HTMLDivElement>--
onClickCaptureMouseEventHandler<HTMLDivElement>--
onContextMenuMouseEventHandler<HTMLDivElement>--
onContextMenuCaptureMouseEventHandler<HTMLDivElement>--
onDoubleClickMouseEventHandler<HTMLDivElement>--
onDoubleClickCaptureMouseEventHandler<HTMLDivElement>--
onGotPointerCapturePointerEventHandler<HTMLDivElement>--
onGotPointerCaptureCapturePointerEventHandler<HTMLDivElement>--
onLostPointerCapturePointerEventHandler<HTMLDivElement>--
onLostPointerCaptureCapturePointerEventHandler<HTMLDivElement>--
onMouseDownMouseEventHandler<HTMLDivElement>--
onMouseDownCaptureMouseEventHandler<HTMLDivElement>--
onMouseEnterMouseEventHandler<HTMLDivElement>--
onMouseLeaveMouseEventHandler<HTMLDivElement>--
onMouseMoveMouseEventHandler<HTMLDivElement>--
onMouseMoveCaptureMouseEventHandler<HTMLDivElement>--
onMouseOutMouseEventHandler<HTMLDivElement>--
onMouseOutCaptureMouseEventHandler<HTMLDivElement>--
onMouseOverMouseEventHandler<HTMLDivElement>--
onMouseOverCaptureMouseEventHandler<HTMLDivElement>--
onMouseUpMouseEventHandler<HTMLDivElement>--
onMouseUpCaptureMouseEventHandler<HTMLDivElement>--
onPointerCancelPointerEventHandler<HTMLDivElement>--
onPointerCancelCapturePointerEventHandler<HTMLDivElement>--
onPointerDownPointerEventHandler<HTMLDivElement>--
onPointerDownCapturePointerEventHandler<HTMLDivElement>--
onPointerEnterPointerEventHandler<HTMLDivElement>--
onPointerLeavePointerEventHandler<HTMLDivElement>--
onPointerMovePointerEventHandler<HTMLDivElement>--
onPointerMoveCapturePointerEventHandler<HTMLDivElement>--
onPointerOutPointerEventHandler<HTMLDivElement>--
onPointerOutCapturePointerEventHandler<HTMLDivElement>--
onPointerOverPointerEventHandler<HTMLDivElement>--
onPointerOverCapturePointerEventHandler<HTMLDivElement>--
onPointerUpPointerEventHandler<HTMLDivElement>--
onPointerUpCapturePointerEventHandler<HTMLDivElement>--
onScrollUIEventHandler<HTMLDivElement>--
onScrollCaptureUIEventHandler<HTMLDivElement>--
onSelectionChange(keys: Selection) => void-Handler that is called when the selection changes.
onTouchCancelTouchEventHandler<HTMLDivElement>--
onTouchCancelCaptureTouchEventHandler<HTMLDivElement>--
onTouchEndTouchEventHandler<HTMLDivElement>--
onTouchEndCaptureTouchEventHandler<HTMLDivElement>--
onTouchMoveTouchEventHandler<HTMLDivElement>--
onTouchMoveCaptureTouchEventHandler<HTMLDivElement>--
onTouchStartTouchEventHandler<HTMLDivElement>--
onTouchStartCaptureTouchEventHandler<HTMLDivElement>--
onTransitionCancelTransitionEventHandler<HTMLDivElement>--
onTransitionCancelCaptureTransitionEventHandler<HTMLDivElement>--
onTransitionEndTransitionEventHandler<HTMLDivElement>--
onTransitionEndCaptureTransitionEventHandler<HTMLDivElement>--
onTransitionRunTransitionEventHandler<HTMLDivElement>--
onTransitionRunCaptureTransitionEventHandler<HTMLDivElement>--
onTransitionStartTransitionEventHandler<HTMLDivElement>--
onTransitionStartCaptureTransitionEventHandler<HTMLDivElement>--
onWheelWheelEventHandler<HTMLDivElement>--
onWheelCaptureWheelEventHandler<HTMLDivElement>--
renderDOMRenderFunction<"div", GridListRenderProps>-Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: * You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). * Only a single root DOM element can be rendered (no fragments). * You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
renderEmptyState(props: GridListRenderProps) => ReactNode-Provides content to display when there are no items in the list.
selectedKeys"all" | Iterable<Key>-The currently selected keys in the collection (controlled).
selectionBehaviorSelectionBehavior"toggle"How multiple selection should behave in the collection.
selectionModeSelectionMode-The type of selection that is allowed in the collection.
shouldSelectOnPressUpboolean-Whether selection should occur on press up instead of press down.
slotstring-A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
styleStyleOrFunction<GridListRenderProps>-The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state.
translate"yes" | "no"--