- Docs
- components
- GridList
GridList
A grid list displays a list of interactive items, with support for keyboard navigation, single or multiple selection, and row actions.
A list can be built using <ul> or <ol> HTML elements, but does not support any user interactions. HTML lists are meant for static content, rather than lists with rich interactions like focusable elements within rows, keyboard navigation, row selection, etc. GridList helps achieve accessible and interactive list components that can be styled as needed.
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).
Installation
npx shadcn@latest add https://backchanel.com/default/grid-listComposed Components
A GridList uses the following components, which may also be used standalone or reused in other components.
Button
A button allows a user to perform an action, with mouse, touch, and keyboard interactions.
Checkbox
A checkbox allows a user to select multiple items from a list of individual items, or to mark one individual item as selected.
Examples
Basic
Dynamic Content
Selection
Single Selection
Multiple Selection
Disallow Empty Selection
Selection Behavior
When selectionBehavior is set to "replace", clicking a row with the mouse replaces the selection with only that row. Using the arrow keys moves both focus and selection. To select multiple rows, modifier keys such as Ctrl, Cmd, and Shift can be used. On touch screen devices, selection always behaves as toggle since modifier keys may not be available.
Row Actions
Rows may also have a row action specified by directly applying onAction on the GridListItem itself. This may be especially convenient in static collections. If onAction is also provided to the GridList, both the grid list's and the row's onAction are called.
Links
Disabled Items
Disabled Behavior
When disabledBehavior is set to selection, interactions such as focus, dragging, or actions can still be performed on disabled rows.
In dynamic collections, it may be more convenient to use the disabledKeys prop at the GridList level instead of isDisabled on individual items. This accepts a list of item ids that are disabled. An item is considered disabled if its key exists in disabledKeys or if it has isDisabled.
Empty State
Drag and Drop
This uses useListData from React Stately to manage the item list. Note that useListData is a convenience hook, not a requirement. You can manage your state however you wish.