GridList

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

Example#

import {GridList, Item, Button} from 'react-aria-components';

<GridList aria-label="Favorite pokemon" selectionMode="multiple">
  <Item textValue="Charizard">
    <MyCheckbox />
    Charizard
    <Button aria-label="Info">ⓘ</Button>
  </Item>
  <Item textValue="Blastoise">
    <MyCheckbox />
    Blastoise
    <Button aria-label="Info">ⓘ</Button>
  </Item>
  <Item textValue="Venusaur">
    <MyCheckbox />
    Venusaur
    <Button aria-label="Info">ⓘ</Button>
  </Item>
  <Item textValue="Pikachu">
    <MyCheckbox />
    Pikachu
    <Button aria-label="Info">ⓘ</Button>
  </Item>
</GridList>

import {
  Button,
  GridList,
  Item
} from 'react-aria-components';

<GridList
  aria-label="Favorite pokemon"
  selectionMode="multiple"
>
  <Item textValue="Charizard">
    <MyCheckbox />
    Charizard
    <Button aria-label="Info">ⓘ</Button>
  </Item>
  <Item textValue="Blastoise">
    <MyCheckbox />
    Blastoise
    <Button aria-label="Info">ⓘ</Button>
  </Item>
  <Item textValue="Venusaur">
    <MyCheckbox />
    Venusaur
    <Button aria-label="Info">ⓘ</Button>
  </Item>
  <Item textValue="Pikachu">
    <MyCheckbox />
    Pikachu
    <Button aria-label="Info">ⓘ</Button>
  </Item>
</GridList>

import {
  Button,
  GridList,
  Item
} from 'react-aria-components';

<GridList
  aria-label="Favorite pokemon"
  selectionMode="multiple"
>
  <Item textValue="Charizard">
    <MyCheckbox />
    Charizard
    <Button aria-label="Info">
      ⓘ
    </Button>
  </Item>
  <Item textValue="Blastoise">
    <MyCheckbox />
    Blastoise
    <Button aria-label="Info">
      ⓘ
    </Button>
  </Item>
  <Item textValue="Venusaur">
    <MyCheckbox />
    Venusaur
    <Button aria-label="Info">
      ⓘ
    </Button>
  </Item>
  <Item textValue="Pikachu">
    <MyCheckbox />
    Pikachu
    <Button aria-label="Info">
      ⓘ
    </Button>
  </Item>
</GridList>

.react-aria-GridList {
  --highlight-background: slateblue;
  --highlight-foreground: white;
  --border-color: var(--spectrum-global-color-gray-400);
  --background-color: var(--page-background);
  --text-color: var(--spectrum-alias-text-color);
  --text-color-disabled: var(--spectrum-alias-text-color-disabled);

  display: flex;
  flex-direction: column;
  gap: 2px;
  max-height: inherit;
  overflow: auto;
  padding: 4px;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--background-color);
  outline: none;
  width: 250px;
  max-height: 300px;
  min-height: 100px;
  box-sizing: border-box;

  &[data-empty] {
    align-items: center;
    justify-content: center;
    font-style: italic;
  }

  &[data-focus-visible] {
    border-color: var(--highlight-background);
    box-shadow: 0 0 0 1px var(--highlight-background);
  }

  .react-aria-Item {
    padding: 0.286rem 0.286rem 0.286rem 0.571rem;
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--text-color);
    font-size: 1.072rem;
    position: relative;
    transform: translateZ(0);

    &[data-focus-visible] {
      box-shadow: inset 0 0 0 2px var(--highlight-background);
    }

    &[data-pressed] {
      background: var(--spectrum-global-color-gray-200);
    }

    &[data-selected] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);

      &[data-focus-visible] {
        box-shadow: inset 0 0 0 2px var(--highlight-background), inset 0 0 0 4px var(--highlight-foreground);
      }

      .react-aria-Button {
        color: var(--highlight-foreground);
        --focus-ring-color: var(--highlight-foreground);
        --hover-highlight: rgb(255 255 255 / 0.1);
        --active-highlight: rgb(255 255 255 / 0.2);
      }
    }

    &[data-disabled] {
      color: var(--text-color-disabled);
    }

    [role=gridcell] {
      display: flex;
      align-items: center;
      gap: 0.571rem;
      min-height: 28px;
    }

    .react-aria-Button:not([slot]) {
      margin-left: auto;
    }
  }

  /* join selected items if :has selector is supported */
  @supports selector(:has(.foo)) {
    gap: 0;

    .react-aria-Item[data-selected]:has(+ [data-selected]),
    .react-aria-Item[data-selected]:has(+ .react-aria-DropIndicator + [data-selected]) {
      border-end-start-radius: 0;
      border-end-end-radius: 0;
    }

    .react-aria-Item[data-selected] + [data-selected],
    .react-aria-Item[data-selected] + .react-aria-DropIndicator + [data-selected] {
      border-start-start-radius: 0;
      border-start-end-radius: 0;
    }
  }
}

.react-aria-Checkbox {
  --deselected-color: gray;
  --deselected-color-pressed: dimgray;
  --selected-color: white;
  --selected-color-pressed: #ddd;
  --checkmark-color: slateblue;
  --focus-ring-color: slateblue;

  width: 1rem;
  height: 1rem;
  border: 2px solid var(--deselected-color);
  border-radius: 4px;
  transition: all 200ms;
  display: flex;
  align-items: center;
  justify-content: center;

  & svg {
    width: 0.857rem;
    height: 0.857rem;
    fill: none;
    stroke: var(--checkmark-color);
    stroke-width: 3px;
    stroke-dasharray: 22px;
    stroke-dashoffset: 66;
    transition: all 200ms;
  }

  &[data-focus-visible] {
    box-shadow: 0 0 0 2px var(--spectrum-alias-background-color-default), 0 0 0 4px var(--focus-ring-color);
  }

  &[data-pressed] {
    border-color: var(--deselected-color-pressed);
  }

  &[data-selected] {
    border-color: var(--selected-color);
    background: var(--selected-color);

    &[data-pressed] {
      border-color: var(--selected-color-pressed);
      background: var(--selected-color-pressed);
    }

    &[data-focus-visible] {
      box-shadow: 0 0 0 2px var(--focus-ring-color), 0 0 0 4px var(--selected-color);
    }

    & svg {
      stroke-dashoffset: 44;
    }
  }

  &[data-disabled] {
    opacity: 0.4;
  }
}

.react-aria-Button {
  background: transparent;
  border: none;
  border-radius: 4px;
  appearance: none;
  vertical-align: middle;
  font-size: 1.2rem;
  text-align: center;
  line-height: 1.2em;
  margin: 0;
  outline: none;
  padding: 0.286rem 0.429rem;
  transition: background 200ms;
  color: var(--spectrum-alias-text-color);
  --focus-ring-color: slateblue;
  --hover-highlight: var(--spectrum-alias-highlight-hover);
  --active-highlight: var(--spectrum-alias-highlight-active);

  &[data-hovered] {
    background: var(--hover-highlight);
  }

  &[data-pressed] {
    background: var(--active-highlight);
  }

  &[data-focus-visible] {
    box-shadow: 0 0 0 2px var(--focus-ring-color);
  }
}

@media (forced-colors: active) {
  .react-aria-GridList {
    forced-color-adjust: none;

    --highlight-background: Highlight;
    --highlight-foreground: HighlightText;
    --border-color: ButtonBorder;
    --background-color: ButtonFace;
    --text-color: ButtonText;
    --text-color-disabled: GrayText;
  }

  .react-aria-Checkbox {
    forced-color-adjust: none;

    --deselected-color: ButtonBorder;
    --deselected-color-pressed: ButtonBorder;
    --selected-color: ButtonFace;
    --selected-color-pressed: ButtonFace;
    --checkmark-color: ButtonText;
    --spectrum-alias-background-color-default: Canvas;
    --focus-ring-color: Highlight;

    &[data-disabled] {
      opacity: 1;
      --deselected-color: GrayText;
      --selected-color: GrayText;
    }
  }

  .react-aria-Button {
    forced-color-adjust: none;
    --focus-ring-color: Highlight;
  }
}

.react-aria-GridList {
  --highlight-background: slateblue;
  --highlight-foreground: white;
  --border-color: var(--spectrum-global-color-gray-400);
  --background-color: var(--page-background);
  --text-color: var(--spectrum-alias-text-color);
  --text-color-disabled: var(--spectrum-alias-text-color-disabled);

  display: flex;
  flex-direction: column;
  gap: 2px;
  max-height: inherit;
  overflow: auto;
  padding: 4px;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--background-color);
  outline: none;
  width: 250px;
  max-height: 300px;
  min-height: 100px;
  box-sizing: border-box;

  &[data-empty] {
    align-items: center;
    justify-content: center;
    font-style: italic;
  }

  &[data-focus-visible] {
    border-color: var(--highlight-background);
    box-shadow: 0 0 0 1px var(--highlight-background);
  }

  .react-aria-Item {
    padding: 0.286rem 0.286rem 0.286rem 0.571rem;
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--text-color);
    font-size: 1.072rem;
    position: relative;
    transform: translateZ(0);

    &[data-focus-visible] {
      box-shadow: inset 0 0 0 2px var(--highlight-background);
    }

    &[data-pressed] {
      background: var(--spectrum-global-color-gray-200);
    }

    &[data-selected] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);

      &[data-focus-visible] {
        box-shadow: inset 0 0 0 2px var(--highlight-background), inset 0 0 0 4px var(--highlight-foreground);
      }

      .react-aria-Button {
        color: var(--highlight-foreground);
        --focus-ring-color: var(--highlight-foreground);
        --hover-highlight: rgb(255 255 255 / 0.1);
        --active-highlight: rgb(255 255 255 / 0.2);
      }
    }

    &[data-disabled] {
      color: var(--text-color-disabled);
    }

    [role=gridcell] {
      display: flex;
      align-items: center;
      gap: 0.571rem;
      min-height: 28px;
    }

    .react-aria-Button:not([slot]) {
      margin-left: auto;
    }
  }

  /* join selected items if :has selector is supported */
  @supports selector(:has(.foo)) {
    gap: 0;

    .react-aria-Item[data-selected]:has(+ [data-selected]),
    .react-aria-Item[data-selected]:has(+ .react-aria-DropIndicator + [data-selected]) {
      border-end-start-radius: 0;
      border-end-end-radius: 0;
    }

    .react-aria-Item[data-selected] + [data-selected],
    .react-aria-Item[data-selected] + .react-aria-DropIndicator + [data-selected] {
      border-start-start-radius: 0;
      border-start-end-radius: 0;
    }
  }
}

.react-aria-Checkbox {
  --deselected-color: gray;
  --deselected-color-pressed: dimgray;
  --selected-color: white;
  --selected-color-pressed: #ddd;
  --checkmark-color: slateblue;
  --focus-ring-color: slateblue;

  width: 1rem;
  height: 1rem;
  border: 2px solid var(--deselected-color);
  border-radius: 4px;
  transition: all 200ms;
  display: flex;
  align-items: center;
  justify-content: center;

  & svg {
    width: 0.857rem;
    height: 0.857rem;
    fill: none;
    stroke: var(--checkmark-color);
    stroke-width: 3px;
    stroke-dasharray: 22px;
    stroke-dashoffset: 66;
    transition: all 200ms;
  }

  &[data-focus-visible] {
    box-shadow: 0 0 0 2px var(--spectrum-alias-background-color-default), 0 0 0 4px var(--focus-ring-color);
  }

  &[data-pressed] {
    border-color: var(--deselected-color-pressed);
  }

  &[data-selected] {
    border-color: var(--selected-color);
    background: var(--selected-color);

    &[data-pressed] {
      border-color: var(--selected-color-pressed);
      background: var(--selected-color-pressed);
    }

    &[data-focus-visible] {
      box-shadow: 0 0 0 2px var(--focus-ring-color), 0 0 0 4px var(--selected-color);
    }

    & svg {
      stroke-dashoffset: 44;
    }
  }

  &[data-disabled] {
    opacity: 0.4;
  }
}

.react-aria-Button {
  background: transparent;
  border: none;
  border-radius: 4px;
  appearance: none;
  vertical-align: middle;
  font-size: 1.2rem;
  text-align: center;
  line-height: 1.2em;
  margin: 0;
  outline: none;
  padding: 0.286rem 0.429rem;
  transition: background 200ms;
  color: var(--spectrum-alias-text-color);
  --focus-ring-color: slateblue;
  --hover-highlight: var(--spectrum-alias-highlight-hover);
  --active-highlight: var(--spectrum-alias-highlight-active);

  &[data-hovered] {
    background: var(--hover-highlight);
  }

  &[data-pressed] {
    background: var(--active-highlight);
  }

  &[data-focus-visible] {
    box-shadow: 0 0 0 2px var(--focus-ring-color);
  }
}

@media (forced-colors: active) {
  .react-aria-GridList {
    forced-color-adjust: none;

    --highlight-background: Highlight;
    --highlight-foreground: HighlightText;
    --border-color: ButtonBorder;
    --background-color: ButtonFace;
    --text-color: ButtonText;
    --text-color-disabled: GrayText;
  }

  .react-aria-Checkbox {
    forced-color-adjust: none;

    --deselected-color: ButtonBorder;
    --deselected-color-pressed: ButtonBorder;
    --selected-color: ButtonFace;
    --selected-color-pressed: ButtonFace;
    --checkmark-color: ButtonText;
    --spectrum-alias-background-color-default: Canvas;
    --focus-ring-color: Highlight;

    &[data-disabled] {
      opacity: 1;
      --deselected-color: GrayText;
      --selected-color: GrayText;
    }
  }

  .react-aria-Button {
    forced-color-adjust: none;
    --focus-ring-color: Highlight;
  }
}

.react-aria-GridList {
  --highlight-background: slateblue;
  --highlight-foreground: white;
  --border-color: var(--spectrum-global-color-gray-400);
  --background-color: var(--page-background);
  --text-color: var(--spectrum-alias-text-color);
  --text-color-disabled: var(--spectrum-alias-text-color-disabled);

  display: flex;
  flex-direction: column;
  gap: 2px;
  max-height: inherit;
  overflow: auto;
  padding: 4px;
  border: 1px solid var(--border-color);
  border-radius: 6px;
  background: var(--background-color);
  outline: none;
  width: 250px;
  max-height: 300px;
  min-height: 100px;
  box-sizing: border-box;

  &[data-empty] {
    align-items: center;
    justify-content: center;
    font-style: italic;
  }

  &[data-focus-visible] {
    border-color: var(--highlight-background);
    box-shadow: 0 0 0 1px var(--highlight-background);
  }

  .react-aria-Item {
    padding: 0.286rem 0.286rem 0.286rem 0.571rem;
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--text-color);
    font-size: 1.072rem;
    position: relative;
    transform: translateZ(0);

    &[data-focus-visible] {
      box-shadow: inset 0 0 0 2px var(--highlight-background);
    }

    &[data-pressed] {
      background: var(--spectrum-global-color-gray-200);
    }

    &[data-selected] {
      background: var(--highlight-background);
      color: var(--highlight-foreground);

      &[data-focus-visible] {
        box-shadow: inset 0 0 0 2px var(--highlight-background), inset 0 0 0 4px var(--highlight-foreground);
      }

      .react-aria-Button {
        color: var(--highlight-foreground);
        --focus-ring-color: var(--highlight-foreground);
        --hover-highlight: rgb(255 255 255 / 0.1);
        --active-highlight: rgb(255 255 255 / 0.2);
      }
    }

    &[data-disabled] {
      color: var(--text-color-disabled);
    }

    [role=gridcell] {
      display: flex;
      align-items: center;
      gap: 0.571rem;
      min-height: 28px;
    }

    .react-aria-Button:not([slot]) {
      margin-left: auto;
    }
  }

  /* join selected items if :has selector is supported */
  @supports selector(:has(.foo)) {
    gap: 0;

    .react-aria-Item[data-selected]:has(+ [data-selected]),
    .react-aria-Item[data-selected]:has(+ .react-aria-DropIndicator + [data-selected]) {
      border-end-start-radius: 0;
      border-end-end-radius: 0;
    }

    .react-aria-Item[data-selected] + [data-selected],
    .react-aria-Item[data-selected] + .react-aria-DropIndicator + [data-selected] {
      border-start-start-radius: 0;
      border-start-end-radius: 0;
    }
  }
}

.react-aria-Checkbox {
  --deselected-color: gray;
  --deselected-color-pressed: dimgray;
  --selected-color: white;
  --selected-color-pressed: #ddd;
  --checkmark-color: slateblue;
  --focus-ring-color: slateblue;

  width: 1rem;
  height: 1rem;
  border: 2px solid var(--deselected-color);
  border-radius: 4px;
  transition: all 200ms;
  display: flex;
  align-items: center;
  justify-content: center;

  & svg {
    width: 0.857rem;
    height: 0.857rem;
    fill: none;
    stroke: var(--checkmark-color);
    stroke-width: 3px;
    stroke-dasharray: 22px;
    stroke-dashoffset: 66;
    transition: all 200ms;
  }

  &[data-focus-visible] {
    box-shadow: 0 0 0 2px var(--spectrum-alias-background-color-default), 0 0 0 4px var(--focus-ring-color);
  }

  &[data-pressed] {
    border-color: var(--deselected-color-pressed);
  }

  &[data-selected] {
    border-color: var(--selected-color);
    background: var(--selected-color);

    &[data-pressed] {
      border-color: var(--selected-color-pressed);
      background: var(--selected-color-pressed);
    }

    &[data-focus-visible] {
      box-shadow: 0 0 0 2px var(--focus-ring-color), 0 0 0 4px var(--selected-color);
    }

    & svg {
      stroke-dashoffset: 44;
    }
  }

  &[data-disabled] {
    opacity: 0.4;
  }
}

.react-aria-Button {
  background: transparent;
  border: none;
  border-radius: 4px;
  appearance: none;
  vertical-align: middle;
  font-size: 1.2rem;
  text-align: center;
  line-height: 1.2em;
  margin: 0;
  outline: none;
  padding: 0.286rem 0.429rem;
  transition: background 200ms;
  color: var(--spectrum-alias-text-color);
  --focus-ring-color: slateblue;
  --hover-highlight: var(--spectrum-alias-highlight-hover);
  --active-highlight: var(--spectrum-alias-highlight-active);

  &[data-hovered] {
    background: var(--hover-highlight);
  }

  &[data-pressed] {
    background: var(--active-highlight);
  }

  &[data-focus-visible] {
    box-shadow: 0 0 0 2px var(--focus-ring-color);
  }
}

@media (forced-colors: active) {
  .react-aria-GridList {
    forced-color-adjust: none;

    --highlight-background: Highlight;
    --highlight-foreground: HighlightText;
    --border-color: ButtonBorder;
    --background-color: ButtonFace;
    --text-color: ButtonText;
    --text-color-disabled: GrayText;
  }

  .react-aria-Checkbox {
    forced-color-adjust: none;

    --deselected-color: ButtonBorder;
    --deselected-color-pressed: ButtonBorder;
    --selected-color: ButtonFace;
    --selected-color-pressed: ButtonFace;
    --checkmark-color: ButtonText;
    --spectrum-alias-background-color-default: Canvas;
    --focus-ring-color: Highlight;

    &[data-disabled] {
      opacity: 1;
      --deselected-color: GrayText;
      --selected-color: GrayText;
    }
  }

  .react-aria-Button {
    forced-color-adjust: none;
    --focus-ring-color: Highlight;
  }
}

Features#

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.

• Item selection – Single or multiple selection, with optional checkboxes, disabled rows, and both toggle and replace selection behaviors.
• Interactive children – List items may include interactive elements such as buttons, checkboxes, menus, etc.
• Actions – Items support optional row actions such as navigation via click, tap, double click, or Enter key.
• Async loading – Support for loading items asynchronously.
• Keyboard navigation – List items and focusable children can be navigated using the arrow keys, along with page up/down, home/end, etc. Typeahead, auto scrolling, and selection modifier keys are supported as well.
• Drag and drop – GridList supports drag and drop to reorder, insert, or update items via mouse, touch, keyboard, and screen reader interactions.
• Touch friendly – Selection and actions adapt their behavior depending on the device. For example, selection is activated via long press on touch when item actions are present.
• Accessible – Follows the ARIA grid pattern, with additional selection announcements via an ARIA live region. Extensively tested across many devices and assistive technologies to ensure announcements and behaviors are consistent.

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).

Anatomy#

A grid list consists of a container element, with rows of data inside. The rows within a list may contain focusable elements or plain text content. If the list supports row selection, each row can optionally include a selection checkbox.

import {GridList, Item, Checkbox, Button} from 'react-aria-components';

<GridList>
  <Item>
    <Button slot="drag" />
    <Checkbox slot="selection" />
  </Item>
</GridList>

import {
  Button,
  Checkbox,
  GridList,
  Item
} from 'react-aria-components';

<GridList>
  <Item>
    <Button slot="drag" />
    <Checkbox slot="selection" />
  </Item>
</GridList>

import {
  Button,
  Checkbox,
  GridList,
  Item
} from 'react-aria-components';

<GridList>
  <Item>
    <Button slot="drag" />
    <Checkbox slot="selection" />
  </Item>
</GridList>

Concepts#

GridList makes use of the following concepts:

Composed components#

A GridList uses the following components, which may also be used standalone or reused in other components.

Examples#

iOS List View

A GridList with swipe gestures, layout animations, and multi selection.

Reusable wrappers#

If you will use a GridList in multiple places in your app, you can wrap all of the pieces into a reusable component. This way, the DOM structure, styling code, and other logic are defined in a single place and reused everywhere to ensure consistency.

This example wraps GridList and all of its children together into a single component which accepts a label prop and children, which are passed through to the right places. The Item component is also wrapped to include a custom checkbox component automatically when the item is multi-selectable, and a drag handle when drag and drop is enabled.

import type {GridListProps, ItemProps} from 'react-aria-components';
import {Button, Checkbox} from 'react-aria-components';

function MyGridList<T extends object>(
  { children, ...props }: GridListProps<T>
) {
  return (
    <GridList {...props}>
      {children}
    </GridList>
  );
}

function MyItem({ children, ...props }: ItemProps) {
  let textValue = typeof children === 'string' ? children : undefined;
  return (
    <Item textValue={textValue} {...props}>
      {({ selectionMode, selectionBehavior, allowsDragging }) => (
        <>
          {/* Add elements for drag and drop and selection. */}
          {allowsDragging && <Button slot="drag">≡</Button>}
          {selectionMode === 'multiple' && selectionBehavior === 'toggle' && (
            <MyCheckbox />
          )}
          {children}
        </>
      )}
    </Item>
  );
}

function MyCheckbox() {
  return (
    <Checkbox slot="selection">
      <svg viewBox="0 0 18 18" aria-hidden="true">
        <polyline points="1 9 7 14 15 4" />
      </svg>
    </Checkbox>
  );
}

<MyGridList aria-label="Ice cream flavors" selectionMode="multiple">
  <MyItem>Chocolate</MyItem>
  <MyItem>Mint</MyItem>
  <MyItem>Strawberry</MyItem>
  <MyItem>Vanilla</MyItem>
</MyGridList>

import type {
  GridListProps,
  ItemProps
} from 'react-aria-components';
import {Button, Checkbox} from 'react-aria-components';

function MyGridList<T extends object>(
  { children, ...props }: GridListProps<T>
) {
  return (
    <GridList {...props}>
      {children}
    </GridList>
  );
}

function MyItem({ children, ...props }: ItemProps) {
  let textValue = typeof children === 'string'
    ? children
    : undefined;
  return (
    <Item textValue={textValue} {...props}>
      {(
        { selectionMode, selectionBehavior, allowsDragging }
      ) => (
        <>
          {/* Add elements for drag and drop and selection. */}
          {allowsDragging && <Button slot="drag">≡</Button>}
          {selectionMode === 'multiple' &&
            selectionBehavior === 'toggle' &&
          <MyCheckbox />}
          {children}
        </>
      )}
    </Item>
  );
}

function MyCheckbox() {
  return (
    <Checkbox slot="selection">
      <svg viewBox="0 0 18 18" aria-hidden="true">
        <polyline points="1 9 7 14 15 4" />
      </svg>
    </Checkbox>
  );
}

<MyGridList
  aria-label="Ice cream flavors"
  selectionMode="multiple"
>
  <MyItem>Chocolate</MyItem>
  <MyItem>Mint</MyItem>
  <MyItem>Strawberry</MyItem>
  <MyItem>Vanilla</MyItem>
</MyGridList>

import type {
  GridListProps,
  ItemProps
} from 'react-aria-components';
import {
  Button,
  Checkbox
} from 'react-aria-components';

function MyGridList<
  T extends object
>(
  { children, ...props }:
    GridListProps<T>
) {
  return (
    <GridList {...props}>
      {children}
    </GridList>
  );
}

function MyItem(
  { children, ...props }:
    ItemProps
) {
  let textValue =
    typeof children ===
        'string'
      ? children
      : undefined;
  return (
    <Item
      textValue={textValue}
      {...props}
    >
      {(
        {
          selectionMode,
          selectionBehavior,
          allowsDragging
        }
      ) => (
        <>
          {/* Add elements for drag and drop and selection. */}
          {allowsDragging &&
            (
              <Button slot="drag">
                ≡
              </Button>
            )}
          {selectionMode ===
              'multiple' &&
            selectionBehavior ===
              'toggle' &&
            (
              <MyCheckbox />
            )}
          {children}
        </>
      )}
    </Item>
  );
}

function MyCheckbox() {
  return (
    <Checkbox slot="selection">
      <svg
        viewBox="0 0 18 18"
        aria-hidden="true"
      >
        <polyline points="1 9 7 14 15 4" />
      </svg>
    </Checkbox>
  );
}

<MyGridList
  aria-label="Ice cream flavors"
  selectionMode="multiple"
>
  <MyItem>
    Chocolate
  </MyItem>
  <MyItem>Mint</MyItem>
  <MyItem>
    Strawberry
  </MyItem>
  <MyItem>
    Vanilla
  </MyItem>
</MyGridList>

Content#

So far, our examples have shown static collections, where the data is hard coded. Dynamic collections, as shown below, can be used when the data comes from an external data source such as an API, or updates over time. In the example below, the rows are provided to the GridList via a render function.

interface ItemValue {
  id: number;
  name: string;
}

function ExampleList(props: GridListProps<ItemValue>) {
  let rows = [
    { id: 1, name: 'Games' },
    { id: 2, name: 'Program Files' },
    { id: 3, name: 'bootmgr' },
    { id: 4, name: 'log.txt' }
  ];

  return (
    <MyGridList
      aria-label="Example dynamic collection List"
      selectionMode="multiple"
      items={rows}      ...props}
    >
      {(item) => (
        <MyItem textValue={item.name}>
          {item.name}
          <Button
            aria-label="Info"
            onPress={() => alert(`Info for ${item.name}...`)}
          >
            ⓘ
          </Button>
        </MyItem>
      )}
    </MyGridList>
  );
}

interface ItemValue {
  id: number;
  name: string;
}

function ExampleList(props: GridListProps<ItemValue>) {
  let rows = [
    { id: 1, name: 'Games' },
    { id: 2, name: 'Program Files' },
    { id: 3, name: 'bootmgr' },
    { id: 4, name: 'log.txt' }
  ];

  return (
    <MyGridList
      aria-label="Example dynamic collection List"
      selectionMode="multiple"
      items={rows}      ...props}
    >
      {(item) => (
        <MyItem textValue={item.name}>
          {item.name}
          <Button
            aria-label="Info"
            onPress={() =>
              alert(`Info for ${item.name}...`)}
          >
            ⓘ
          </Button>
        </MyItem>
      )}
    </MyGridList>
  );
}

interface ItemValue {
  id: number;
  name: string;
}

function ExampleList(
  props: GridListProps<
    ItemValue
  >
) {
  let rows = [
    {
      id: 1,
      name: 'Games'
    },
    {
      id: 2,
      name:
        'Program Files'
    },
    {
      id: 3,
      name: 'bootmgr'
    },
    {
      id: 4,
      name: 'log.txt'
    }
  ];

  return (
    <MyGridList
      aria-label="Example dynamic collection List"
      selectionMode="multiple"
      items={rows}      ...props}
    >
      {(item) => (
        <MyItem
          textValue={item
            .name}
        >
          {item.name}
          <Button
            aria-label="Info"
            onPress={() =>
              alert(
                `Info for ${item.name}...`
              )}
          >
            ⓘ
          </Button>
        </MyItem>
      )}
    </MyGridList>
  );
}

Selection#

Single selection#

By default, GridList doesn't allow row selection but this can be enabled using the selectionMode prop. Use defaultSelectedKeys to provide a default set of selected rows. Note that the value of the selected keys must match the id prop of the row.

The example below enables single selection mode, and uses defaultSelectedKeys to select the id with key equal to 2. A user can click on a different row to change the selection, or click on the same row again to deselect it entirely.

// Using the example above
<ExampleList
  aria-label="List with single selection"
  selectionMode="single"
  defaultSelectedKeys={[2]}/>

// Using the example above
<ExampleList
  aria-label="List with single selection"
  selectionMode="single"
  defaultSelectedKeys={[2]}/>

// Using the example above
<ExampleList
  aria-label="List with single selection"
  selectionMode="single"
  defaultSelectedKeys={[
    2
  ]}/>

Multiple selection#

Multiple selection can be enabled by setting selectionMode to multiple. Our example displays checkboxes when the list allows multiple selection.

<ExampleList
  aria-label="List with multiple selection"
  selectionMode="multiple"  defaultSelectedKeys={[2, 4]} />

<ExampleList
  aria-label="List with multiple selection"
  selectionMode="multiple"  defaultSelectedKeys={[2, 4]} />

<ExampleList
  aria-label="List with multiple selection"
  selectionMode="multiple"  defaultSelectedKeys={[
    2,
    4
  ]}
/>

Disallow empty selection#

GridList also supports a disallowEmptySelection prop which forces the user to have at least one row in the List selected at all times. In this mode, if a single row is selected and the user presses it, it will not be deselected.

<ExampleList
  aria-label="List with disallowed empty selection"
  selectionMode="multiple"
  defaultSelectedKeys={[2]}
  disallowEmptySelection/>

<ExampleList
  aria-label="List with disallowed empty selection"
  selectionMode="multiple"
  defaultSelectedKeys={[2]}
  disallowEmptySelection/>

<ExampleList
  aria-label="List with disallowed empty selection"
  selectionMode="multiple"
  defaultSelectedKeys={[
    2
  ]}
  disallowEmptySelection/>

Controlled selection#

To programmatically control row selection, use the selectedKeys prop paired with the onSelectionChange callback. The id prop from the selected rows will be passed into the callback when the row is pressed, allowing you to update state accordingly.

import type {Selection} from 'react-aria-components';

function PokemonList(props: GridListProps<ItemValue>) {
  let rows = [
    {id: 1, name: 'Charizard'},
    {id: 2, name: 'Blastoise'},
    {id: 3, name: 'Venusaur'},
    {id: 4, name: 'Pikachu'}
  ];

  let [selectedKeys, setSelectedKeys] = React.useState<Selection>(new Set([2]));

  return (
    <MyGridList
      aria-label="List with controlled selection"
      items={rows}
      selectionMode="multiple"
      selectedKeys={selectedKeys}
      onSelectionChange={setSelectedKeys}      {...props}>
      {item => <MyItem>{item.name}</MyItem>}
    </MyGridList>
  );
}

import type {Selection} from 'react-aria-components';

function PokemonList(props: GridListProps<ItemValue>) {
  let rows = [
    { id: 1, name: 'Charizard' },
    { id: 2, name: 'Blastoise' },
    { id: 3, name: 'Venusaur' },
    { id: 4, name: 'Pikachu' }
  ];

  let [selectedKeys, setSelectedKeys] = React.useState<
    Selection
  >(new Set([2]));

  return (
    <MyGridList
      aria-label="List with controlled selection"
      items={rows}
      selectionMode="multiple"
      selectedKeys={selectedKeys}
      onSelectionChange={setSelectedKeys}      ...props}
    >
      {(item) => <MyItem>{item.name}</MyItem>}
    </MyGridList>
  );
}

import type {Selection} from 'react-aria-components';

function PokemonList(
  props: GridListProps<
    ItemValue
  >
) {
  let rows = [
    {
      id: 1,
      name: 'Charizard'
    },
    {
      id: 2,
      name: 'Blastoise'
    },
    {
      id: 3,
      name: 'Venusaur'
    },
    {
      id: 4,
      name: 'Pikachu'
    }
  ];

  let [
    selectedKeys,
    setSelectedKeys
  ] = React.useState<
    Selection
  >(new Set([2]));

  return (
    <MyGridList
      aria-label="List with controlled selection"
      items={rows}
      selectionMode="multiple"
      selectedKeys={selectedKeys}
      onSelectionChange={setSelectedKeys}      ...props}
    >
      {(item) => (
        <MyItem>
          {item.name}
        </MyItem>
      )}
    </MyGridList>
  );
}

Selection behavior#

By default, GridList uses the "toggle" selection behavior, which behaves like a checkbox group: clicking, tapping, or pressing the Space or Enter keys toggles selection for the focused row. Using the arrow keys moves focus but does not change selection. The "toggle" selection mode is often paired with a checkbox in each row as an explicit affordance for selection.

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.

These selection styles implement the behaviors defined in Aria Practices.

<PokemonList
  aria-label="List with replace selection behavior"
  selectionMode="multiple"
  selectionBehavior="replace"/>

<PokemonList
  aria-label="List with replace selection behavior"
  selectionMode="multiple"
  selectionBehavior="replace"/>

<PokemonList
  aria-label="List with replace selection behavior"
  selectionMode="multiple"
  selectionBehavior="replace"/>

Row actions#

GridList supports row actions via the onAction prop, which is useful for functionality such as navigation. When nothing is selected, the list performs actions by default when clicking or tapping a row. Items may be selected using the checkbox, or by long pressing on touch devices. When at least one item is selected, the list is in selection mode, and clicking or tapping a row toggles the selection. Actions may also be triggered via the Enter key, and selection using the Space key.

This behavior is slightly different when selectionBehavior="replace", where single clicking selects the row and actions are performed via double click. Touch and keyboard behaviors are unaffected.

<div style={{ display: 'flex', flexWrap: 'wrap', gap: 24 }}>
  <ExampleList
    aria-label="Checkbox selection list with row actions"
    selectionMode="multiple"
    selectionBehavior="toggle"
    onAction={key => alert(`Opening item ${key}...`)}  />
  <ExampleList
    aria-label="Highlight selection list with row actions"
    selectionMode="multiple"
    selectionBehavior="replace"
    onAction={key => alert(`Opening item ${key}...`)}  />
</div>

<div style={{ display: 'flex', flexWrap: 'wrap', gap: 24 }}>
  <ExampleList
    aria-label="Checkbox selection list with row actions"
    selectionMode="multiple"
    selectionBehavior="toggle"
    onAction={key => alert(`Opening item ${key}...`)}  />
  <ExampleList
    aria-label="Highlight selection list with row actions"
    selectionMode="multiple"
    selectionBehavior="replace"
    onAction={key => alert(`Opening item ${key}...`)}  />
</div>

<div
  style={{
    display: 'flex',
    flexWrap: 'wrap',
    gap: 24
  }}
>
  <ExampleList
    aria-label="Checkbox selection list with row actions"
    selectionMode="multiple"
    selectionBehavior="toggle"
    onAction={(key) =>
      alert(
        `Opening item ${key}...`
      )}  />
  <ExampleList
    aria-label="Highlight selection list with row actions"
    selectionMode="multiple"
    selectionBehavior="replace"
    onAction={(key) =>
      alert(
        `Opening item ${key}...`
      )}  />
</div>

Links#

Items in a GridList may also be links to another page or website. This can be achieved by passing the href prop to the <Item> component. Links behave the same way as described above for row actions depending on the selectionMode and selectionBehavior.

<MyGridList aria-label="Links" selectionMode="multiple">
  <MyItem href="https://adobe.com/" target="_blank">Adobe</MyItem>
  <MyItem href="https://apple.com/" target="_blank">Apple</MyItem>
  <MyItem href="https://google.com/" target="_blank">Google</MyItem>
  <MyItem href="https://microsoft.com/" target="_blank">Microsoft</MyItem>
</MyGridList>

<MyGridList aria-label="Links" selectionMode="multiple">
  <MyItem href="https://adobe.com/" target="_blank">
    Adobe
  </MyItem>
  <MyItem href="https://apple.com/" target="_blank">
    Apple
  </MyItem>
  <MyItem href="https://google.com/" target="_blank">
    Google
  </MyItem>
  <MyItem href="https://microsoft.com/" target="_blank">
    Microsoft
  </MyItem>
</MyGridList>

<MyGridList
  aria-label="Links"
  selectionMode="multiple"
>
  <MyItem
    href="https://adobe.com/"
    target="_blank"
  >
    Adobe
  </MyItem>
  <MyItem
    href="https://apple.com/"
    target="_blank"
  >
    Apple
  </MyItem>
  <MyItem
    href="https://google.com/"
    target="_blank"
  >
    Google
  </MyItem>
  <MyItem
    href="https://microsoft.com/"
    target="_blank"
  >
    Microsoft
  </MyItem>
</MyGridList>

Client side routing#

The <Item> component works with frameworks and client side routers like Next.js and React Router. As with other React Aria components that support links, this works via the RouterProvider component at the root of your app. See the client side routing guide to learn how to set this up.

Disabled items#

You can disable specific rows by providing an array of keys to GridList via the disabledKeys prop. This will disable all interactions on disabled rows, unless the disabledBehavior prop is used to change this behavior. Note that you are responsible for the styling of disabled rows, however, the selection checkbox will be automatically disabled.

// Using the example above
<PokemonList
  aria-label="List with disabled rows"
  selectionMode="multiple"
  disabledKeys={[3]}/>

// Using the example above
<PokemonList
  aria-label="List with disabled rows"
  selectionMode="multiple"
  disabledKeys={[3]}/>

// Using the example above
<PokemonList
  aria-label="List with disabled rows"
  selectionMode="multiple"
  disabledKeys={[3]}/>

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

<PokemonList
  aria-label="List with selection disabled for disabled rows"
  selectionMode="multiple"
  disabledKeys={[3]}
  disabledBehavior="selection"/>

<PokemonList
  aria-label="List with selection disabled for disabled rows"
  selectionMode="multiple"
  disabledKeys={[3]}
  disabledBehavior="selection"/>

<PokemonList
  aria-label="List with selection disabled for disabled rows"
  selectionMode="multiple"
  disabledKeys={[3]}
  disabledBehavior="selection"/>

Asynchronous loading#

This example uses the useAsyncList hook to handle asynchronous loading of data from a server. You may additionally want to display a spinner to indicate the loading state to the user, or support features like infinite scroll to load more data.

import {useAsyncList} from '@react-stately/data';

interface Character {
  name: string;
}

function AsyncList() {
  let list = useAsyncList<Character>({
    async load({ signal, cursor }) {
      if (cursor) {
        cursor = cursor.replace(/^http:\/\//i, 'https://');
      }

      let res = await fetch(
        cursor || `https://swapi.py4e.com/api/people/?search=`,
        { signal }
      );
      let json = await res.json();

      return {
        items: json.results,
        cursor: json.next
      };
    }
  });

  return (
    <MyGridList
      selectionMode="multiple"
      aria-label="Async loading ListView example"
      items={list.items}
    >
      {(item) => <MyItem id={item.name}>{item.name}</MyItem>}
    </MyGridList>
  );
}

import {useAsyncList} from '@react-stately/data';

interface Character {
  name: string;
}

function AsyncList() {
  let list = useAsyncList<Character>({
    async load({ signal, cursor }) {
      if (cursor) {
        cursor = cursor.replace(/^http:\/\//i, 'https://');
      }

      let res = await fetch(
        cursor ||
          `https://swapi.py4e.com/api/people/?search=`,
        { signal }
      );
      let json = await res.json();

      return {
        items: json.results,
        cursor: json.next
      };
    }
  });

  return (
    <MyGridList
      selectionMode="multiple"
      aria-label="Async loading ListView example"
      items={list.items}
    >
      {(item) => <MyItem id={item.name}>{item.name}
      </MyItem>}
    </MyGridList>
  );
}

import {useAsyncList} from '@react-stately/data';

interface Character {
  name: string;
}

function AsyncList() {
  let list =
    useAsyncList<
      Character
    >({
      async load(
        {
          signal,
          cursor
        }
      ) {
        if (cursor) {
          cursor = cursor
            .replace(
              /^http:\/\//i,
              'https://'
            );
        }

        let res =
          await fetch(
            cursor ||
              `https://swapi.py4e.com/api/people/?search=`,
            { signal }
          );
        let json =
          await res
            .json();

        return {
          items:
            json.results,
          cursor:
            json.next
        };
      }
    });

  return (
    <MyGridList
      selectionMode="multiple"
      aria-label="Async loading ListView example"
      items={list.items}
    >
      {(item) => (
        <MyItem
          id={item.name}
        >
          {item.name}
        </MyItem>
      )}
    </MyGridList>
  );
}

Empty state#

Use the renderEmptyState prop to customize what the GridList will display if there are no items.

<GridList
  aria-label="Search results"
  renderEmptyState={() => 'No results found.'}>
  {[]}
</GridList>

<GridList
  aria-label="Search results"
  renderEmptyState={() => 'No results found.'}>
  {[]}
</GridList>

<GridList
  aria-label="Search results"
  renderEmptyState={() =>
    'No results found.'}>
  {[]}
</GridList>

Drag and drop#

GridList supports drag and drop interactions when the dragAndDropHooks prop is provided using the useDragAndDrop hook. Users can drop data on the list as a whole, on individual items, insert new items between existing ones, or reorder items.

React Aria supports traditional mouse and touch based drag and drop, but also implements keyboard and screen reader friendly interactions. Users can press Enter on a draggable element to enter drag and drop mode. Then, they can press Tab to navigate between drop targets. A droppable collection is treated as a single drop target, so that users can easily tab past it to get to the next drop target. Within a droppable collection, keys such as ArrowDown and ArrowUp can be used to select a drop position, such as on an item, or between items.

Draggable items must include a focusable drag handle using a <Button slot="drag">. This enables keyboard and screen reader users to initiate drag and drop. The MyItem component defined in the reusable wrappers section above includes this automatically when the list allows dragging.

See the drag and drop introduction to learn more.

Reorderable#

This example shows a basic list that allows users to reorder items via drag and drop. This is enabled using the onReorder event handler, provided to the useDragAndDrop hook. The getItems function must also be implemented for items to become draggable. See below for more details.

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.

import {useListData} from 'react-stately';
import {useDragAndDrop} from 'react-aria-components';

function Example() {
  let list = useListData({
    initialItems: [
      { id: 1, name: 'Adobe Photoshop' },
      { id: 2, name: 'Adobe XD' },
      { id: 3, name: 'Adobe Dreamweaver' },
      { id: 4, name: 'Adobe InDesign' },
      { id: 5, name: 'Adobe Connect' }
    ]
  });

  let { dragAndDropHooks } = useDragAndDrop({
    getItems: (keys) =>
      [...keys].map((key) => ({ 'text/plain': list.getItem(key).name })),
    onReorder(e) {
      if (e.target.dropPosition === 'before') {
        list.moveBefore(e.target.key, e.keys);
      } else if (e.target.dropPosition === 'after') {
        list.moveAfter(e.target.key, e.keys);
      }
    }
  });
  return (
    <MyGridList
      aria-label="Reorderable list"
      selectionMode="multiple"
      items={list.items}
      dragAndDropHooks={dragAndDropHooks}    >
      {(item) => <MyItem>{item.name}</MyItem>}
    </MyGridList>
  );
}

import {useListData} from 'react-stately';
import {useDragAndDrop} from 'react-aria-components';

function Example() {
  let list = useListData({
    initialItems: [
      { id: 1, name: 'Adobe Photoshop' },
      { id: 2, name: 'Adobe XD' },
      { id: 3, name: 'Adobe Dreamweaver' },
      { id: 4, name: 'Adobe InDesign' },
      { id: 5, name: 'Adobe Connect' }
    ]
  });

  let { dragAndDropHooks } = useDragAndDrop({
    getItems: (keys) =>
      [...keys].map((key) => ({
        'text/plain': list.getItem(key).name
      })),
    onReorder(e) {
      if (e.target.dropPosition === 'before') {
        list.moveBefore(e.target.key, e.keys);
      } else if (e.target.dropPosition === 'after') {
        list.moveAfter(e.target.key, e.keys);
      }
    }
  });
  return (
    <MyGridList
      aria-label="Reorderable list"
      selectionMode="multiple"
      items={list.items}
      dragAndDropHooks={dragAndDropHooks}    >
      {(item) => <MyItem>{item.name}</MyItem>}
    </MyGridList>
  );
}

import {useListData} from 'react-stately';
import {useDragAndDrop} from 'react-aria-components';

function Example() {
  let list = useListData(
    {
      initialItems: [
        {
          id: 1,
          name:
            'Adobe Photoshop'
        },
        {
          id: 2,
          name:
            'Adobe XD'
        },
        {
          id: 3,
          name:
            'Adobe Dreamweaver'
        },
        {
          id: 4,
          name:
            'Adobe InDesign'
        },
        {
          id: 5,
          name:
            'Adobe Connect'
        }
      ]
    }
  );

  let {
    dragAndDropHooks
  } = useDragAndDrop({
    getItems: (keys) =>
      [...keys].map(
        (key) => ({
          'text/plain':
            list.getItem(
              key
            ).name
        })
      ),
    onReorder(e) {
      if (
        e.target
          .dropPosition ===
          'before'
      ) {
        list.moveBefore(
          e.target.key,
          e.keys
        );
      } else if (
        e.target
          .dropPosition ===
          'after'
      ) {
        list.moveAfter(
          e.target.key,
          e.keys
        );
      }
    }
  });
  return (
    <MyGridList
      aria-label="Reorderable list"
      selectionMode="multiple"
      items={list.items}
      dragAndDropHooks={dragAndDropHooks}    >
      {(item) => (
        <MyItem>
          {item.name}
        </MyItem>
      )}
    </MyGridList>
  );
}

.react-aria-Item {
  &[data-allows-dragging] {
    padding-left: 4px;
  }

  &[data-dragging] {
    opacity: 0.6;
  }

  [slot=drag] {
    all: unset;
    width: 15px;
    text-align: center;

    &[data-focus-visible] {
      border-radius: 4px;
      box-shadow: 0 0 0 2px var(--highlight-background);
    }
  }

  &[data-selected] {
    [slot=drag][data-focus-visible] {
      box-shadow: 0 0 0 2px var(--highlight-foreground);
    }
  }
}

.react-aria-DropIndicator {
  &[data-drop-target] {
    outline: 1px solid var(--highlight-background);
  }

  @supports not selector(:has(.foo)) {
    /* Undo gap in browsers that don't support :has */
    margin-bottom: -2px;
  }
}

.react-aria-Item {
  &[data-allows-dragging] {
    padding-left: 4px;
  }

  &[data-dragging] {
    opacity: 0.6;
  }

  [slot=drag] {
    all: unset;
    width: 15px;
    text-align: center;

    &[data-focus-visible] {
      border-radius: 4px;
      box-shadow: 0 0 0 2px var(--highlight-background);
    }
  }

  &[data-selected] {
    [slot=drag][data-focus-visible] {
      box-shadow: 0 0 0 2px var(--highlight-foreground);
    }
  }
}

.react-aria-DropIndicator {
  &[data-drop-target] {
    outline: 1px solid var(--highlight-background);
  }

  @supports not selector(:has(.foo)) {
    /* Undo gap in browsers that don't support :has */
    margin-bottom: -2px;
  }
}

.react-aria-Item {
  &[data-allows-dragging] {
    padding-left: 4px;
  }

  &[data-dragging] {
    opacity: 0.6;
  }

  [slot=drag] {
    all: unset;
    width: 15px;
    text-align: center;

    &[data-focus-visible] {
      border-radius: 4px;
      box-shadow: 0 0 0 2px var(--highlight-background);
    }
  }

  &[data-selected] {
    [slot=drag][data-focus-visible] {
      box-shadow: 0 0 0 2px var(--highlight-foreground);
    }
  }
}

.react-aria-DropIndicator {
  &[data-drop-target] {
    outline: 1px solid var(--highlight-background);
  }

  @supports not selector(:has(.foo)) {
    /* Undo gap in browsers that don't support :has */
    margin-bottom: -2px;
  }
}

Custom drag preview#

By default, the drag preview shown under the user's pointer or finger is a copy of the original element that started the drag. A custom preview can be rendered by implementing the renderDragPreview function, passed to useDragAndDrop. This receives the dragged data that was returned by getItems, and returns a rendered preview for those items.

This example renders a custom drag preview which shows the number of items being dragged.

import {useListData} from 'react-stately';
import {useDragAndDrop} from 'react-aria-components';

function Example() {
  let {dragAndDropHooks} = useDragAndDrop({
    // ...
    renderDragPreview(items) {
      return (
        <div className="drag-preview">
          {items[0]['text/plain']}
          <span className="badge">{items.length}</span>
        </div>
      );
    }  });

  // ...
}

import {useListData} from 'react-stately';
import {useDragAndDrop} from 'react-aria-components';

function Example() {
  let {dragAndDropHooks} = useDragAndDrop({
    // ...
    renderDragPreview(items) {
      return (
        <div className="drag-preview">
          {items[0]['text/plain']}
          <span className="badge">{items.length}</span>
        </div>
      );
    }  });

  // ...
}

import {useListData} from 'react-stately';
import {useDragAndDrop} from 'react-aria-components';

function Example() {
  let {
    dragAndDropHooks
  } = useDragAndDrop({
    // ...
    renderDragPreview(
      items
    ) {
      return (
        <div className="drag-preview">
          {items[0][
            'text/plain'
          ]}
          <span className="badge">
            {items
              .length}
          </span>
        </div>
      );
    }  });

  // ...
}

.drag-preview {
  width: 150px;
  padding: 4px 8px;
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 4px;
  background: slateblue;
  color: white;
  border-radius: 4px;

  .badge {
    background: white;
    color: slateblue;
    padding: 0 8px;
    border-radius: 4px;
  }
}

.drag-preview {
  width: 150px;
  padding: 4px 8px;
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 4px;
  background: slateblue;
  color: white;
  border-radius: 4px;

  .badge {
    background: white;
    color: slateblue;
    padding: 0 8px;
    border-radius: 4px;
  }
}

.drag-preview {
  width: 150px;
  padding: 4px 8px;
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 4px;
  background: slateblue;
  color: white;
  border-radius: 4px;

  .badge {
    background: white;
    color: slateblue;
    padding: 0 8px;
    border-radius: 4px;
  }
}

Drag data#

Data for draggable items can be provided in multiple formats at once. This allows drop targets to choose data in a format that they understand. For example, you could serialize a complex object as JSON in a custom format for use within your own application, and also provide plain text and/or rich HTML fallbacks that can be used when a user drops data in an external application (e.g. an email message).

This can be done by returning multiple keys for an item from the getItems function. Types can either be a standard mime type for interoperability with external applications, or a custom string for use within your own app.

This example provides representations of each item as plain text, HTML, and a custom app-specific data format. Dropping on the drop targets in this page will use the custom data format to render formatted items. If you drop in an external application supporting rich text, the HTML representation will be used. Dropping in a text editor will use the plain text format.

function DraggableGridList() {
  let items = new Map([
    ['ps', { name: 'Photoshop', style: 'strong' }],
    ['xd', { name: 'XD', style: 'strong' }],
    ['id', { name: 'InDesign', style: 'strong' }],
    ['dw', { name: 'Dreamweaver', style: 'em' }],
    ['co', { name: 'Connect', style: 'em' }]
  ]);

  let { dragAndDropHooks } = useDragAndDrop({
    getItems(keys) {
      return [...keys].map((key) => {
        let item = items.get(key as string)!;
        return {
          'text/plain': item.name,
          'text/html': `<${item.style}>${item.name}</${item.style}>`,
          'custom-app-type': JSON.stringify({ id: key, ...item })
        };
      });
    }  });

  return (
    <MyGridList
      aria-label="Draggable list"
      selectionMode="multiple"
      items={items}
      dragAndDropHooks={dragAndDropHooks}
    >
      {([id, item]) => (
        <MyItem id={id} textValue={item.name}>
          {React.createElement(item.style || 'span', null, item.name)}
        </MyItem>
      )}
    </MyGridList>
  );
}

<div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
  <DraggableGridList />
  {/* see below */}
  <DroppableGridList />
</div>

function DraggableGridList() {
  let items = new Map([
    ['ps', { name: 'Photoshop', style: 'strong' }],
    ['xd', { name: 'XD', style: 'strong' }],
    ['id', { name: 'InDesign', style: 'strong' }],
    ['dw', { name: 'Dreamweaver', style: 'em' }],
    ['co', { name: 'Connect', style: 'em' }]
  ]);

  let { dragAndDropHooks } = useDragAndDrop({
    getItems(keys) {
      return [...keys].map((key) => {
        let item = items.get(key as string)!;
        return {
          'text/plain': item.name,
          'text/html':
            `<${item.style}>${item.name}</${item.style}>`,
          'custom-app-type': JSON.stringify({
            id: key,
            ...item
          })
        };
      });
    }  });

  return (
    <MyGridList
      aria-label="Draggable list"
      selectionMode="multiple"
      items={items}
      dragAndDropHooks={dragAndDropHooks}
    >
      {([id, item]) => (
        <MyItem id={id} textValue={item.name}>
          {React.createElement(
            item.style || 'span',
            null,
            item.name
          )}
        </MyItem>
      )}
    </MyGridList>
  );
}

<div
  style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}
>
  <DraggableGridList />
  {/* see below */}
  <DroppableGridList />
</div>

function DraggableGridList() {
  let items = new Map([
    ['ps', {
      name: 'Photoshop',
      style: 'strong'
    }],
    ['xd', {
      name: 'XD',
      style: 'strong'
    }],
    ['id', {
      name: 'InDesign',
      style: 'strong'
    }],
    ['dw', {
      name:
        'Dreamweaver',
      style: 'em'
    }],
    ['co', {
      name: 'Connect',
      style: 'em'
    }]
  ]);

  let {
    dragAndDropHooks
  } = useDragAndDrop({
    getItems(keys) {
      return [...keys]
        .map((key) => {
          let item =
            items.get(
              key as string
            )!;
          return {
            'text/plain':
              item.name,
            'text/html':
              `<${item.style}>${item.name}</${item.style}>`,
            'custom-app-type':
              JSON
                .stringify(
                  {
                    id:
                      key,
                    ...item
                  }
                )
          };
        });
    }  });

  return (
    <MyGridList
      aria-label="Draggable list"
      selectionMode="multiple"
      items={items}
      dragAndDropHooks={dragAndDropHooks}
    >
      {([id, item]) => (
        <MyItem
          id={id}
          textValue={item
            .name}
        >
          {React
            .createElement(
              item
                .style ||
                'span',
              null,
              item.name
            )}
        </MyItem>
      )}
    </MyGridList>
  );
}

<div
  style={{
    display: 'flex',
    gap: 12,
    flexWrap: 'wrap'
  }}
>
  <DraggableGridList />
  {/* see below */}
  <DroppableGridList />
</div>

Dropping on the collection#

Dropping on the GridList as a whole can be enabled using the onRootDrop event. When a valid drag hovers over the GridList, it receives the isDropTarget state and can be styled using the [data-drop-target] CSS selector.

interface Item {
  id: number;
  name: string;
}

function Example() {
  let [items, setItems] = React.useState<Item[]>([]);

  let { dragAndDropHooks } = useDragAndDrop({
    async onRootDrop(e) {
      let items = await Promise.all(e.items.map(async (item, i) => {
        let name = item.kind === 'text'
          ? await item.getText('text/plain')
          : item.name;
        return { id: i, name };
      }));
      setItems(items);
    }  });

  return (
    <div style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}>
      <DraggableGridList />
      <MyGridList
        aria-label="Droppable list"
        items={items}
        dragAndDropHooks={dragAndDropHooks}
        renderEmptyState={() => 'Drop items here'}
      >
        {(item) => <Item>{item.name}</Item>}
      </MyGridList>
    </div>
  );
}

interface Item {
  id: number;
  name: string;
}

function Example() {
  let [items, setItems] = React.useState<Item[]>([]);

  let { dragAndDropHooks } = useDragAndDrop({
    async onRootDrop(e) {
      let items = await Promise.all(
        e.items.map(async (item, i) => {
          let name = item.kind === 'text'
            ? await item.getText('text/plain')
            : item.name;
          return { id: i, name };
        })
      );
      setItems(items);
    }  });

  return (
    <div
      style={{ display: 'flex', gap: 12, flexWrap: 'wrap' }}
    >
      <DraggableGridList />
      <MyGridList
        aria-label="Droppable list"
        items={items}
        dragAndDropHooks={dragAndDropHooks}
        renderEmptyState={() => 'Drop items here'}
      >
        {(item) => <Item>{item.name}</Item>}
      </MyGridList>
    </div>
  );
}