Grid

This is experimental and may introduce breaking changes or be removed altogether in patch and minor versions without notice. Learn more in Experimental features.

Accessible Grid component that enables users to navigate the information or interactive elements it contains using directional navigation keys. The items are organized in a two-dimensional container. It follows the WAI-ARIA Grid Pattern.

#Installation

npm install reakit

Learn more in Get started.

#Usage

cellcellcell

import {
  unstable_useGridState as useGridState,
  unstable_Grid as Grid,
  unstable_GridRow as GridRow,
  unstable_GridCell as GridCell,
} from "reakit/Grid";

function Example() {
  const grid = useGridState();
  return (
    <Grid {...grid} aria-label="My grid">
      <GridRow {...grid}>
        <GridCell {...grid}>cell</GridCell>
        <GridCell {...grid}>cell</GridCell>
        <GridCell {...grid}>cell</GridCell>
      </GridRow>
      <GridRow {...grid}>
        <GridCell {...grid}>cell</GridCell>
        <GridCell {...grid}>cell</GridCell>
        <GridCell {...grid}>cell</GridCell>
      </GridRow>
      <GridRow {...grid}>
        <GridCell {...grid}>cell</GridCell>
        <GridCell {...grid}>cell</GridCell>
        <GridCell {...grid}>cell</GridCell>
      </GridRow>
    </Grid>
  );
}

#Accessibility

Grid has role grid.
Grid extends the accessibility features of Composite.
GridRow has role row.
GridRow extends the accessibility features of CompositeGroup.
GridCell has role gridcell.
GridCell extends the accessibility features of CompositeItem.

Learn more in Accessibility.

#Composition

Grid uses Composite.
GridRow uses CompositeGroup.
GridCell uses CompositeItem.

Learn more in Composition.

#Props

#`useGridState`

baseId string

ID that will serve as a base for all the items IDs.
unstable_virtual boolean

If enabled, the composite element will act as an aria-activedescendant container instead of roving tabindex. DOM focus will remain on the composite while its items receive virtual focus.
rtl boolean

Determines how next and previous functions will behave. If rtl is set to true, they will be inverted. This only affects the composite widget behavior. You still need to set dir="rtl" on HTML/CSS.
orientation "horizontal" | "vertical" | undefined

Defines the orientation of the composite widget. If the composite has a single row or column (one-dimensional), the orientation value determines which arrow keys can be used to move focus:
- undefined: all arrow keys work.
- horizontal: only left and right arrow keys work.
- vertical: only up and down arrow keys work.
It doesn't have any effect on two-dimensional composites.
currentId string | null | undefined

The current focused item id.
- undefined will automatically focus the first enabled composite item.
- null will focus the base composite element and users will be able to navigate out of it using arrow keys.
- If currentId is initially set to null, the base composite element itself will have focus and users will be able to navigate to it using arrow keys.
loop boolean | "horizontal" | "vertical"

On one-dimensional composites:
- true loops from the last item to the first item and vice-versa.
- horizontal loops only if orientation is horizontal or not set.
- vertical loops only if orientation is vertical or not set.
- If currentId is initially set to null, the composite element will be focused in between the last and first items.
On two-dimensional composites:
- true loops from the last row/column item to the first item in the same row/column and vice-versa. If it's the last item in the last row, it moves to the first item in the first row and vice-versa.
- horizontal loops only from the last row item to the first item in the same row.
- vertical loops only from the last column item to the first item in the column row.
- If currentId is initially set to null, vertical loop will have no effect as moving down from the last row or up from the first row will focus the composite element.
- If wrap matches the value of loop, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.
wrap boolean | "horizontal" | "vertical"

Has effect only on two-dimensional composites. If enabled, moving to the next item from the last one in a row or column will focus the first item in the next row or column and vice-versa.
- true wraps between rows and columns.
- horizontal wraps only between rows.
- vertical wraps only between columns.
- If loop matches the value of wrap, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.
shift boolean

Has effect only on two-dimensional composites. If enabled, moving up or down when there's no next item or the next item is disabled will shift to the item right before it.

#`Grid`

disabled boolean | undefined

Same as the HTML attribute.
focusable boolean | undefined

When an element is disabled, it may still be focusable. It works similarly to readOnly on form elements. In this case, only aria-disabled will be set.

12 state props

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

baseId string

ID that will serve as a base for all the items IDs.
unstable_virtual boolean

If enabled, the composite element will act as an aria-activedescendant container instead of roving tabindex. DOM focus will remain on the composite while its items receive virtual focus.
orientation "horizontal" | "vertical" | undefined

Defines the orientation of the composite widget. If the composite has a single row or column (one-dimensional), the orientation value determines which arrow keys can be used to move focus:
- undefined: all arrow keys work.
- horizontal: only left and right arrow keys work.
- vertical: only up and down arrow keys work.
It doesn't have any effect on two-dimensional composites.
currentId string | null | undefined

The current focused item id.
- undefined will automatically focus the first enabled composite item.
- null will focus the base composite element and users will be able to navigate out of it using arrow keys.
- If currentId is initially set to null, the base composite element itself will have focus and users will be able to navigate to it using arrow keys.
wrap boolean | "horizontal" | "vertical"

Has effect only on two-dimensional composites. If enabled, moving to the next item from the last one in a row or column will focus the first item in the next row or column and vice-versa.
- true wraps between rows and columns.
- horizontal wraps only between rows.
- vertical wraps only between columns.
- If loop matches the value of wrap, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.
unstable_moves number

Stores the number of moves that have been performed by calling move, next, previous, up, down, first or last.
groups Group[]

Lists all the composite groups with their id and DOM ref. This state is automatically updated when registerGroup and unregisterGroup are called.
items Item[]

Lists all the composite items with their id, DOM ref, disabled state and groupId if any. This state is automatically updated when registerItem and unregisterItem are called.
setCurrentId (value: SetStateAction<string | null | undefine...

Sets currentId. This is different from composite.move as this only updates the currentId state without moving focus. When the composite widget gets focused by the user, the item referred by the currentId state will get focus.
first () => void

Moves focus to the first item.
last () => void

Moves focus to the last item.
move (id: string | null) => void

Moves focus to a given item ID.

#`GridCell`

disabled boolean | undefined

Same as the HTML attribute.
focusable boolean | undefined

When an element is disabled, it may still be focusable. It works similarly to readOnly on form elements. In this case, only aria-disabled will be set.
id string | undefined

Same as the HTML attribute.

15 state props

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

baseId string

ID that will serve as a base for all the items IDs.
unstable_virtual boolean

If enabled, the composite element will act as an aria-activedescendant container instead of roving tabindex. DOM focus will remain on the composite while its items receive virtual focus.
orientation "horizontal" | "vertical" | undefined

Defines the orientation of the composite widget. If the composite has a single row or column (one-dimensional), the orientation value determines which arrow keys can be used to move focus:
- undefined: all arrow keys work.
- horizontal: only left and right arrow keys work.
- vertical: only up and down arrow keys work.
It doesn't have any effect on two-dimensional composites.
unstable_moves number

Stores the number of moves that have been performed by calling move, next, previous, up, down, first or last.
currentId string | null | undefined

The current focused item id.
- undefined will automatically focus the first enabled composite item.
- null will focus the base composite element and users will be able to navigate out of it using arrow keys.
- If currentId is initially set to null, the base composite element itself will have focus and users will be able to navigate to it using arrow keys.
items Item[]

Lists all the composite items with their id, DOM ref, disabled state and groupId if any. This state is automatically updated when registerItem and unregisterItem are called.
setCurrentId (value: SetStateAction<string | null | undefine...

Sets currentId. This is different from composite.move as this only updates the currentId state without moving focus. When the composite widget gets focused by the user, the item referred by the currentId state will get focus.
first () => void

Moves focus to the first item.
last () => void

Moves focus to the last item.
registerItem (item: Item) => void

Registers a composite item.
unregisterItem (id: string) => void

Unregisters a composite item.
next (unstable_allTheWay?: boolean | undefined) => void

Moves focus to the next item.
previous (unstable_allTheWay?: boolean | undefined) => void

Moves focus to the previous item.
up (unstable_allTheWay?: boolean | undefined) => void

Moves focus to the item above.
down (unstable_allTheWay?: boolean | undefined) => void

Moves focus to the item below.

#`GridRow`

id string | undefined

Same as the HTML attribute.

6 state props

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

baseId string

ID that will serve as a base for all the items IDs.
registerGroup (group: Group) => void

Registers a composite group.
unregisterGroup (id: string) => void

Unregisters a composite group.
currentId string | null | undefined

The current focused item id.
- undefined will automatically focus the first enabled composite item.
- null will focus the base composite element and users will be able to navigate out of it using arrow keys.
- If currentId is initially set to null, the base composite element itself will have focus and users will be able to navigate to it using arrow keys.
unstable_moves number

Stores the number of moves that have been performed by calling move, next, previous, up, down, first or last.
items Item[]

Lists all the composite items with their id, DOM ref, disabled state and groupId if any. This state is automatically updated when registerItem and unregisterItem are called.

Grid

#Installation

#Usage

#Accessibility

#Composition

#Props

#useGridState

#Grid

#GridCell

#GridRow

#`useGridState`

#`Grid`

#`GridCell`

#`GridRow`