JollyUI
  1. Docs
  2. components
  3. 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.

Charizard
Blastoise
Venusaur
Pikachu

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://jollyui.dev/default/grid-list

Composed 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

Charizard
Blastoise
Venusaur
Pikachu

Dynamic Content

Games
Program Files
bootmgr
log.txt

Selection

Single Selection

Charizard
Blastoise
Venusaur
Pikachu

Multiple Selection

Charizard
Blastoise
Venusaur
Pikachu

Disallow Empty Selection

Charizard
Blastoise
Venusaur
Pikachu

Selection Behavior

Charizard
Blastoise
Venusaur
Pikachu

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

Selection Mode: Toggle
Charizard
Blastoise
Venusaur
Pikachu
Selection Mode: Replace
Charizard
Blastoise
Venusaur
Pikachu

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.

Games
Program Files
bootmgr
log.txt
Adobe
Apple
Google
Microsoft

Disabled Items

Charizard
Blastoise
Venusaur
Pikachu

Disabled Behavior

When disabledBehavior is set to selection, interactions such as focus, dragging, or actions can still be performed on disabled rows.

Charizard
Blastoise
Venusaur
Pikachu

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.

Games
Program Files
bootmgr
log.txt

Empty State

No results found.

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.

Adobe Photoshop
Adobe XD
Adobe Dreamweaver
Adobe InDesign
Adobe Connect

Drag Between Lists

Adobe Photoshop
Adobe XD
Documents
Adobe InDesign
Utilities
Adobe AfterEffects
Pictures
Adobe Fresco
Apps
Adobe Illustrator
Adobe Lightroom
Adobe Dreamweaver