GridList

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

Theme 
ImageDesert SunsetPNG • 2/3/2024
ImageHiking TrailJPEG • 1/10/2022
ImageLionJPEG • 8/28/2021
ImageMountain SunrisePNG • 3/15/2015
ImageGiraffe tonguePNG • 11/27/2019
ImageGolden HourWEBP • 7/24/2024
ImageArchitecturePNG • 12/24/2016
ImagePeeking leopardJPEG • 3/2/2016
ImageRoofsJPEG • 4/24/2025
ImageHalf Dome DeerDNG • 8/28/2018
layout 
selectionMode 
Example
GridList.tsx
GridList.css
import {Text} from 'react-aria-components';
import {GridList, GridListItem} from './GridList';

<GridList
  aria-label="Photos"
  selectionMode="multiple"
  layout="grid">
  <GridListItem textValue="Desert Sunset">
    <img src="https://images.unsplash.com/photo-1705034598432-1694e203cdf3?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={400} alt="" />
    <Text>Desert Sunset</Text>
    <Text slot="description">PNG • 2/3/2024</Text>
  </GridListItem>
  <GridListItem textValue="Hiking Trail">
    <img src="https://images.unsplash.com/photo-1722233987129-61dc344db8b6?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={900} alt="" />
    <Text>Hiking Trail</Text>
    <Text slot="description">JPEG • 1/10/2022</Text>
  </GridListItem>
  <GridListItem textValue="Lion">
    <img src="https://images.unsplash.com/photo-1629812456605-4a044aa38fbc?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={899} alt="" />
    <Text>Lion</Text>
    <Text slot="description">JPEG • 8/28/2021</Text>
  </GridListItem>
  <GridListItem textValue="Mountain Sunrise">
    <img src="https://images.unsplash.com/photo-1722172118908-1a97c312ce8c?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={900} alt="" />
    <Text>Mountain Sunrise</Text>
    <Text slot="description">PNG • 3/15/2015</Text>
  </GridListItem>
  <GridListItem textValue="Giraffe tongue">
    <img src="https://images.unsplash.com/photo-1574870111867-089730e5a72b?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={900} alt="" />
    <Text>Giraffe tongue</Text>
    <Text slot="description">PNG • 11/27/2019</Text>
  </GridListItem>
  <GridListItem textValue="Golden Hour">
    <img src="https://images.unsplash.com/photo-1718378037953-ab21bf2cf771?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={402} alt="" />
    <Text>Golden Hour</Text>
    <Text slot="description">WEBP • 7/24/2024</Text>
  </GridListItem>
  <GridListItem textValue="Architecture">
    <img src="https://images.unsplash.com/photo-1721661657253-6621d52db753?w=600&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHx0b3BpYy1mZWVkfDYxfE04alZiTGJUUndzfHxlbnwwfHx8fHw%3D" width={600} height={900} alt="" />
    <Text>Architecture</Text>
    <Text slot="description">PNG • 12/24/2016</Text>
  </GridListItem>
  <GridListItem textValue="Peeking leopard">
    <img src="https://images.unsplash.com/photo-1456926631375-92c8ce872def?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={400} alt="" />
    <Text>Peeking leopard</Text>
    <Text slot="description">JPEG • 3/2/2016</Text>
  </GridListItem>
  <GridListItem textValue="Roofs">
    <img src="https://images.unsplash.com/photo-1721598359121-363311b3b263?w=600&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHx0b3BpYy1mZWVkfDc0fE04alZiTGJUUndzfHxlbnwwfHx8fHw%3D" width={600} height={900} alt="" />
    <Text>Roofs</Text>
    <Text slot="description">JPEG • 4/24/2025</Text>
  </GridListItem>
  <GridListItem textValue="Half Dome Deer">
    <img src="https://images.unsplash.com/photo-1472396961693-142e6e269027?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={990} alt="" />
    <Text>Half Dome Deer</Text>
    <Text slot="description">DNG • 8/28/2018</Text>
  </GridListItem>
</GridList>

Content

GridList follows the Collection Components API, accepting both static and dynamic collections. This example shows a dynamic collection, passing a list of objects to the items prop, and a function to render the children.

ImageA Ficus Lyrata LeafBy Clay Banks
ImageItalian beachBy Alan Bajura
ImageForest roadBy Artem Stoliar
ImageSnowy AuroraBy Janosch Diggelmann
ImageA blue and white firework is seen from aboveBy Janosch Diggelmann
ImageSnowy MountainBy Daniil Silantev
ImagePastel SunsetBy Marek Piwnicki
ImageSnowy BirchesBy Simon Berger
ImageSnowy Lake ReflectionsBy Daniel Seßler
ImageRocky night skyBy Dennis Haug
ImageA pine tree covered in snow in a forestBy Anita Austvika
ImageThe sun shines through the trees in the forestBy Joyce G
ImageA blurry photo of a field of flowersBy Eugene Golovesov
ImageA foggy road lined with trees and grassBy Ingmar H
ImageA close up of a green palm treeBy Junel Mujar
ImageA green leaf floating on top of a body of waterBy Allec Gomes
ImageLeafy plantsBy Joshua Michaels
ImageA view of a mountain covered in fogBy iuliu illes
ImageA field with tall grass and fog in the backgroundBy Ingmar H
ImageA close up of a wave on a sandy beachBy Jonathan Borba
ImageDesert texturesBy Braden Jarvis
ImageTew Falls, waterfall, in Hamilton, Canada.By Andre Portolesi
ImageCave light raysBy Intricate Explorer
ImageSalt Marshes, Isle of Harris, ScotlandBy Nils Leonhardt
ImageAn aerial view of a snow covered forestBy Lukas Hädrich
ImageTall grassBy Ingmar H
ImageLarches on Maple Pass, WashingtonBy Noelle
ImageHeart NebulaBy Arnaud Girault
ImageA pile of shells sitting on top of a sandy beachBy Toa Heftiba
import {GridList, GridListItem} from './GridList';
import {Text} from 'react-aria-components';

function Example() { return ( <GridList
aria-label="Nature photos" selectionMode="multiple" layout="grid" items={images}> {(image) => ( <GridListItem textValue={image.title}> <img src={image.image} width={image.width} height={image.height} alt="" /> <Text>{image.title}</Text> <Text slot="description">By {image.user}</Text> </GridListItem> )} </GridList> ); }

Asynchronous loading

Use renderEmptyState to display a spinner during initial load. To enable infinite scrolling, render a <GridListLoadMoreItem> at the end of the list. Use whatever data fetching library you prefer – this example uses useAsyncList from react-stately.

import {GridList, GridListItem, GridListLoadMoreItem} from './GridList';
import {Collection, Text} from 'react-aria-components';
import {ProgressCircle} from './ProgressCircle';
import {useAsyncList} from '@react-stately/data';

type Item = {
  id: string;
  description?: string;
  alt_description?: string;
  urls: {regular: string};
  width: number;
  height: number;
  user: {name: string};
};

function AsyncLoadingExample() {
  let list = useAsyncList<Item, number | null>({
    async load({signal, cursor, items}) {
      let page = cursor || 1;
      let res = await fetch(
        `https://api.unsplash.com/topics/nature/photos?page=${page}&per_page=30&client_id=AJuU-FPh11hn7RuumUllp4ppT8kgiLS7LtOHp_sp4nc`,
        {signal}
      );
      let nextItems = await res.json();
      // Filter duplicates which might be returned by the API.
      let existingKeys = new Set(items.map(i => i.id));
      nextItems = nextItems.filter(i => !existingKeys.has(i.id) && (i.description || i.alt_description));
      return {items: nextItems, cursor: nextItems.length ? page + 1 : null};
    }
  });

  return (
    <GridList
      aria-label="Nature photos"
      layout="grid"
      selectionMode="multiple"
      renderEmptyState={() => (
        <ProgressCircle isIndeterminate aria-label="Loading..." />
      )}>
      <Collection items={list.items}>
        {(item) => (
          <GridListItem textValue={item.description || item.alt_description}>
            <img src={item.urls.regular} width={item.width} height={item.height} alt="" />
            <Text>{item.description || item.alt_description}</Text>
            <Text slot="description">By {item.user.name}</Text>
          </GridListItem>
        )}
      </Collection>
      <GridListLoadMoreItem
        onLoadMore={list.loadMore}
        isLoading={list.loadingState === 'loadingMore'} />
    </GridList>
  );
}

Use the href prop on a <GridListItem> to create a link. Link interactions vary depending on the selection behavior. See the selection guide for more details.

ImageTropical island
ImageBryce Canyon
ImageSnowy river
ImageOcean waves
ImageMount Kazbek at Dawn
ImageSnowy mountain sunrise
ImageMount Blum
ImageSunset
selectionBehavior 
import {GridList, GridListItem} from './GridList';
import {Text} from 'react-aria-components';

<GridList layout="grid" items={images} aria-label="Links" selectionMode="multiple"> {image => ( <GridListItem href={image.href} target="_blank" textValue={image.title}> <img src={image.image} width={image.width} height={image.height} alt="" /> <Text>{image.title}</Text> </GridListItem> )} </GridList>

Empty state

No results found.
import {GridList} from './GridList';

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

Sections alpha

Use the <GridListSection> component to group options. A <GridListHeader> element may also be included to label the section. Sections without a header must have an aria-label.

Fruit
ImageApplePNG • 9/2/2021
ImagePeachJPEG • 1/16/2022
ImageBlueberryJPEG • 11/30/2020
Vegetables
ImageBroccoliPNG • 5/30/2023
ImageBrussels SproutsPNG • 7/3/2021
ImagePeasPNG • 4/20/2020
import {GridList, GridListItem} from './GridList';
import {GridListHeader, GridListSection, Text} from 'react-aria-components';

<GridList
  layout="grid"
  aria-label="Photos">
    <GridListSection>
      <GridListHeader>Fruit</GridListHeader>
      <GridListItem textValue="Apple">
        <img src="https://images.unsplash.com/photo-1630563451961-ac2ff27616ab?q=80&w=687&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={400} />
        <Text>Apple</Text>
        <Text slot="description">PNG • 9/2/2021</Text>
      </GridListItem>
      <GridListItem textValue="Peach">
        <img src="https://images.unsplash.com/photo-1642372849486-f88b963cb734?q=80&w=2858&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={900} />
        <Text>Peach</Text>
        <Text slot="description">JPEG • 1/16/2022</Text>
      </GridListItem>
      <GridListItem textValue="Blueberry">
        <img src="https://images.unsplash.com/photo-1606757389667-45c2024f9fa4?q=80&w=1740&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={900} />
        <Text>Blueberry</Text>
        <Text slot="description">JPEG • 11/30/2020</Text>
      </GridListItem>
    </GridListSection>
    <GridListSection>
      <GridListHeader>Vegetables</GridListHeader>
      <GridListItem textValue="Broccoli">
        <img src="https://images.unsplash.com/photo-1685504445355-0e7bdf90d415?q=80&w=928&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={900} />
        <Text>Broccoli</Text>
        <Text slot="description">PNG • 5/30/2023</Text>
      </GridListItem>
      <GridListItem textValue="Brussels Sprouts">
        <img src="https://images.unsplash.com/photo-1685504507286-dc290728c01a?q=80&w=1740&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={900} />
        <Text>Brussels Sprouts</Text>
        <Text slot="description">PNG • 7/3/2021</Text>
      </GridListItem>
      <GridListItem textValue="Peas">
        <img src="https://images.unsplash.com/photo-1587411768345-867e228218c8?q=80&w=1160&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={900} />
        <Text>Peas</Text>
        <Text slot="description">PNG • 4/20/2020</Text>
      </GridListItem>
    </GridListSection>
</GridList>

Selection and actions

Use the selectionMode prop to enable single or multiple selection. The selected items can be controlled via the selectedKeys prop, matching the id prop of the items. The onAction event handles item actions. Items can be disabled with the isDisabled prop. See the selection guide for more details.

ImageDesert SunsetPNG • 2/3/2024
ImageHiking TrailJPEG • 1/10/2022
ImageLionJPEG • 8/28/2021
ImageMountain SunrisePNG • 3/15/2015
ImageGiraffe tonguePNG • 11/27/2019
ImageGolden HourWEBP • 7/24/2024
ImageArchitecturePNG • 12/24/2016
ImagePeeking leopardJPEG • 3/2/2016
ImageRoofsJPEG • 4/24/2025
ImageHalf Dome DeerDNG • 8/28/2018

Current selection:

selectionMode 
selectionBehavior 
disabledBehavior 
disallowEmptySelection 
import {type Selection, Text} from 'react-aria-components';
import {GridList, GridListItem} from './GridList';
import {useState} from 'react';

function Example(props) {
  let [selected, setSelected] = useState<Selection>(new Set());

  return (
    <>
      <GridList
        {...props}
        aria-label="Nature photos"
        layout="grid"
        selectionMode="multiple"
        selectedKeys={selected}
        onSelectionChange={setSelected}
        onAction={key => alert(`Clicked ${key}`)}
      >
        <GridListItem id={1} textValue="Desert Sunset">
          <img src="https://images.unsplash.com/photo-1705034598432-1694e203cdf3?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={400} alt="" />
          <Text>Desert Sunset</Text>
          <Text slot="description">PNG • 2/3/2024</Text>
        </GridListItem>
        <GridListItem id={2} isDisabled textValue="Hiking Trail">
          <img src="https://images.unsplash.com/photo-1722233987129-61dc344db8b6?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={900} alt="" />
          <Text>Hiking Trail</Text>
          <Text slot="description">JPEG • 1/10/2022</Text>
        </GridListItem>
        <GridListItem id={3} textValue="Lion">
          <img src="https://images.unsplash.com/photo-1629812456605-4a044aa38fbc?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={899} alt="" />
          <Text>Lion</Text>
          <Text slot="description">JPEG • 8/28/2021</Text>
        </GridListItem>
        <GridListItem id={4} textValue="Mountain Sunrise">
          <img src="https://images.unsplash.com/photo-1722172118908-1a97c312ce8c?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={900} alt="" />
          <Text>Mountain Sunrise</Text>
          <Text slot="description">PNG • 3/15/2015</Text>
        </GridListItem>
        <GridListItem id={5} textValue="Giraffe tongue">
          <img src="https://images.unsplash.com/photo-1574870111867-089730e5a72b?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={900} alt="" />
          <Text>Giraffe tongue</Text>
          <Text slot="description">PNG • 11/27/2019</Text>
        </GridListItem>
        <GridListItem id={6} textValue="Golden Hour">
          <img src="https://images.unsplash.com/photo-1718378037953-ab21bf2cf771?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={402} alt="" />
          <Text>Golden Hour</Text>
          <Text slot="description">WEBP • 7/24/2024</Text>
        </GridListItem>
        <GridListItem id={7} textValue="Architecture">
          <img src="https://images.unsplash.com/photo-1721661657253-6621d52db753?w=600&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHx0b3BpYy1mZWVkfDYxfE04alZiTGJUUndzfHxlbnwwfHx8fHw%3D" width={600} height={900} alt="" />
          <Text>Architecture</Text>
          <Text slot="description">PNG • 12/24/2016</Text>
        </GridListItem>
        <GridListItem id={8} textValue="Peeking leopard">
          <img src="https://images.unsplash.com/photo-1456926631375-92c8ce872def?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={400} alt="" />
          <Text>Peeking leopard</Text>
          <Text slot="description">JPEG • 3/2/2016</Text>
        </GridListItem>
        <GridListItem id={9} textValue="Roofs">
          <img src="https://images.unsplash.com/photo-1721598359121-363311b3b263?w=600&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHx0b3BpYy1mZWVkfDc0fE04alZiTGJUUndzfHxlbnwwfHx8fHw%3D" width={600} height={900} alt="" />
          <Text>Roofs</Text>
          <Text slot="description">JPEG • 4/24/2025</Text>
        </GridListItem>
        <GridListItem id={10} textValue="Half Dome Deer">
          <img src="https://images.unsplash.com/photo-1472396961693-142e6e269027?q=80&w=600&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" width={600} height={990} alt="" />
          <Text>Half Dome Deer</Text>
          <Text slot="description">DNG • 8/28/2018</Text>
        </GridListItem>
      </GridList>
      <p>Current selection: {selected === 'all' ? 'all' : [...selected].join(', ')}</p>
    </>
  );
}

Drag and drop

GridList supports drag and drop interactions when the dragAndDropHooks prop is provided using the 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 drag and drop via mouse, touch, keyboard, and screen reader interactions. See the drag and drop guide to learn more.

ImageA Ficus Lyrata Leaf in the sunlight (2/2) (IG: @clay.banks)Clay Banks
Imagebeach of Italyalan bajura
ImageA winding road in the middle of a forestArtem Stoliar
ImageA green and purple aurora over a snow covered forestJanosch Diggelmann
ImageA blue and white firework is seen from aboveJanosch Diggelmann
ImageA snow covered mountain with a sky backgroundDaniil Silantev
Image"Pastel Sunset"Marek Piwnicki
ImageLeave the weight behind! You must make yourself light to strive upwards — to reach the light. (A serene winter landscape featuring a dense collection of bare, white trees.)Simon Berger
ImageA snow covered tree with a sky backgroundDaniil Silantev
ImageA lake surrounded by trees covered in snowDaniel Seßler
ImageThe night sky with stars above a rock formationDennis Haug
ImageA pine tree covered in snow in a forestAnita Austvika
ImageThe sun shines through the trees in the forestJoyce G
ImageA blurry photo of a field of flowersEugene Golovesov
ImageA foggy road lined with trees and grassIngmar H
ImageA close up of a green palm treeJunel Mujar
ImageA green leaf floating on top of a body of waterAllec Gomes
Imagegreen-leafed plantJoshua Michaels
ImageA view of a mountain covered in fogiuliu illes
ImageA field with tall grass and fog in the backgroundIngmar H
ImageA close up of a wave on a sandy beachJonathan Borba
ImageDesert texturesBraden Jarvis
ImageTew Falls, waterfall, in Hamilton, Canada.Andre Portolesi
ImageFind me on Instagram! @intricateexplorerIntricate Explorer
ImageSalt Marshes, Isle of Harris, Scotland by Nils Leonhardt. Visit my website: https://nilsleonhardt.com/storytelling-harris/ Instagram: @am.basteirNils Leonhardt
ImageAn aerial view of a snow covered forestLukas Hädrich
ImageA close up of a tall grass with a sky in the backgroundIngmar H
ImageLarches on Maple Pass, Washingtonnoelle
ImageIC 1805 La nébuleuse du coeurarnaud girault
ImageA pile of shells sitting on top of a sandy beachToa Heftiba
import {GridList, GridListItem} from './GridList';
import {useDragAndDrop, Text, useListData} from 'react-aria-components';

function Example() { let list = useListData({ initialItems: images
}); let {dragAndDropHooks} = useDragAndDrop({ getItems: (keys, items: typeof list.items) => items.map(item => ({'text/plain': item.title})), 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 ( <GridList aria-label="Reorderable list" layout="grid" selectionMode="multiple" items={list.items} dragAndDropHooks={dragAndDropHooks} > {image => ( <GridListItem textValue={image.title}> <img src={image.image} width={image.width} height={image.height} alt="" /> <Text>{image.title}</Text> <Text slot="description">{image.user}</Text> </GridListItem> )} </GridList> ); }

Examples

API

DocumentsItemSelectioncheckboxDragbutton12 itemsOnboardingPDFBudgetXLSSales PitchPPTDragbutton
<GridList>
  <GridListItem>
    <Button slot="drag" />
    <Checkbox slot="selection" /> or <SelectionIndicator />
  </GridListItem>
  <GridListLoadMoreItem />
</GridList>

GridList

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

NameTypeDefault
disallowTypeAheadbooleanDefault: false

Whether typeahead navigation is disabled.

dragAndDropHooks<NoInfer<object>>Default:

The drag and drop hooks returned by useDragAndDrop used to enable drag and drop behavior for the GridList.

layout'stack''grid'Default: 'stack'

Whether the items are arranged in a stack or grid.

keyboardNavigationBehavior'arrow''tab'Default: 'arrow'

Whether keyboard navigation to focusable elements within grid list items is via the left/right arrow keys or the tab key.

childrenReactNode(item: object) => ReactNodeDefault:

The contents of the collection.

itemsIterable<T>Default:

Item objects in the collection.

renderEmptyState(props: ) => ReactNodeDefault:

Provides content to display when there are no items in the list.

dependenciesReadonlyArray<any>Default:

Values that should invalidate the item cache when using dynamic collections.

selectionModeDefault:

The type of selection that is allowed in the collection.

selectionBehaviorDefault: "toggle"

How multiple selection should behave in the collection.

selectedKeys'all'Iterable<Key>Default:

The currently selected keys in the collection (controlled).

defaultSelectedKeys'all'Iterable<Key>Default:

The initial selected keys in the collection (uncontrolled).

onSelectionChange(keys: ) => voidDefault:

Handler that is called when the selection changes.

disabledKeysIterable<Key>Default:

The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.

disabledBehaviorDefault: "all"

Whether disabledKeys applies to all interactions, or only selection.

disallowEmptySelectionbooleanDefault:

Whether the collection allows empty selection.

shouldSelectOnPressUpbooleanDefault:

Whether selection should occur on press up instead of press down.

escapeKeyBehavior'clearSelection''none'Default: '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.

Default className: react-aria-GridList

Render PropCSS Selector
isEmptyCSS Selector: [data-empty]
Whether the list has no items and should display its empty state.
isFocusedCSS Selector: [data-focused]
Whether the grid list is currently focused.
isFocusVisibleCSS Selector: [data-focus-visible]
Whether the grid list is currently keyboard focused.
isDropTargetCSS Selector: [data-drop-target]
Whether the grid list is currently the active drop target.
layoutCSS Selector: [data-layout="stack | grid"]
Whether the items are arranged in a stack or grid.
stateCSS Selector:
State of the grid list.

GridListSection

A GridListSection represents a section within a GridList.

NameType
idKey

The unique id of the section.

valueobject

The object value that this section represents. When using dynamic collections, this is set automatically.

childrenReactNode(item: object) => ReactElement

Static child items or a function to render children.

itemsIterable<object>

Item objects in the section.

dependenciesReadonlyArray<any>

Values that should invalidate the item cache when using dynamic collections.

Default className: react-aria-GridListSection

GridListHeader

<GridListHeader> labels the section within a GridList. It accepts all HTML attributes.

GridListItem

A GridListItem represents an individual item in a GridList.

NameType
idKey

The unique id of the item.

valueobject

The object value that this item represents. When using dynamic collections, this is set automatically.

textValuestring

A string representation of the item's contents, used for features like typeahead.

isDisabledboolean

Whether the item is disabled.

children<>

The children of the component. A function may be provided to alter the children based on component state.

Default className: react-aria-GridListItem

Render PropCSS Selector
isHoveredCSS Selector: [data-hovered]
Whether the item is currently hovered with a mouse.
isPressedCSS Selector: [data-pressed]
Whether the item is currently in a pressed state.
isSelectedCSS Selector: [data-selected]
Whether the item is currently selected.
isFocusedCSS Selector: [data-focused]
Whether the item is currently focused.
isFocusVisibleCSS Selector: [data-focus-visible]
Whether the item is currently keyboard focused.
isDisabledCSS Selector: [data-disabled]
Whether the item is non-interactive, i.e. both selection and actions are disabled and the item may not be focused. Dependent on disabledKeys and disabledBehavior.
selectionModeCSS Selector: [data-selection-mode="single | multiple"]
The type of selection that is allowed in the collection.
selectionBehaviorCSS Selector:
The selection behavior for the collection.

GridListLoadMoreItem

NameTypeDefault
childrenReactNodeDefault:

The load more spinner to render when loading additional items.

isLoadingbooleanDefault:

Whether or not the loading spinner should be rendered or not.

scrollOffsetnumberDefault: 1

The amount of offset from the bottom of your scrollable region that should trigger load more. Uses a percentage value relative to the scroll body's client height. Load more is then triggered when your current scroll position's distance from the bottom of the currently loaded list of items is less than or equal to the provided value. (e.g. 1 = 100% of the scroll region's height).

onLoadMore() => anyDefault:

Handler that is called when more items should be loaded, e.g. while scrolling near the bottom.

Default className: react-aria-GridListLoadMoreItem