Grid List

Installation

Install the component via the CLI in one command.

npx shadcn@latest add @intentui/grid-list

Composed components

Manual installation

Use this approach if you prefer to install and wire up the component yourself instead of using the CLI.

npm install react-aria-components tailwind-merge

Anatomy

import { GridList, GridListItem } from "@/components/ui/grid-list"

const items = [
  { id: "1", name: "The Beatles" },
  ...
]

<GridList
  selectionMode="single"
  items={items}
  aria-label="Select your favorite bands"
  className="min-w-64"
>
  {(item) => <GridListItem id={item.id}>{item.name}</GridList.Item>}
</GridList>

Examples

Multiple selection

To enable multiple selections, set the selectionMode prop to multiple. Since this prop has no default value, you must define it explicitly.

Note that I haven't set an id for the grid list item as the items already have default IDs. However, you should specify the id prop for each grid list item like this:

{(item) => <GridListItem id={item.name}>{item.name}</GridListItem>}

Drag and drop

The grid list supports drag and drop functionalities if you use the dragAndDropHooks prop along with the useDragAndDrop hook. You can drop data on the entire list, individual items, add new items between existing ones, or rearrange items.

Dragging between items

You can move items between positions within the grid list.

Render empty state

The grid list can display an empty state when no items are available using the renderEmptyState prop.

Infinite scrolling

The grid list can handle large datasets efficiently with infinite scrolling. This allows for loading more data as the user scrolls down, improving performance and user experience.

Section

The grid list supports sections, allowing you to group items under different headings.

Controlled

The grid list can be controlled, which means the parent component manages the selection state of each item.

Disabled

Similar to how the Tag Group component can be disabled using isDisabled for children and disabledKeys for the parent, the Grid List supports similar functionality. For example, items "Led Zeppelin" and "The Rolling Stones" are disabled.

To disable items via the parent component, you can use the disabledKeys prop like this:

<GridList
  items={items}
  aria-label="Select your favorite bands"
  selectionMode="multiple"
  disabledKeys={[2,5]}
  className="min-w-64"
>
  {(item) => <GridListItem id={item.id}>{item.name}</GridListItem>}
</GridList>

Component API

GridList

The GridList component displays selectable items in a grid or list.

GridListDescription

The GridListDescription component renders secondary text for a grid list item.

GridListEmptyState

The GridListEmptyState component renders content when a grid list is empty.

GridListHeader

The GridListHeader component renders header content for a grid list item.

GridListItem

The GridListItem component represents one grid list item.

GridListLabel

The GridListLabel component renders label text for a grid list item.

GridListSection

The GridListSection component groups related grid list items.

GridListSpacer

The GridListSpacer component adds layout spacing inside grid list items.

GridListStart

The GridListStart component renders leading content in a grid list item.

See the React Aria for the full API reference.