Cells

A fully interactive, accessible, user interface component that allows user to select and edit values across a spreadsheet-like grid of cells.

Installation

You can install this component via the shadcn CLI.

npx shadcn@latest add https://jakeisonline.com/playground/registry/cells.json

Usage

import { Cell, CellRow, Cells } from "@/components/ui/cells"

<Cells>
  <CellRow>
    <Cell name="cell_1" label="Cell 1" initialValue="1" autoActive />
    <Cell name="cell_2" label="Cell 2" initialValue="2" />
    <Cell name="cell_3" label="Cell 3" initialValue="3" />
  </CellRow>
  <CellRow>
    <Cell name="cell_4" label="Cell 4" initialValue="4" />
    <Cell name="cell_5" label="Cell 5" initialValue="5" />
    <Cell name="cell_6" label="Cell 6" initialValue="6" />
  </CellRow>
  <CellRow>
    <Cell name="cell_7" label="Cell 7" initialValue="7" />
    <Cell name="cell_8" label="Cell 8" initialValue="8" />
    <Cell name="cell_9" label="Cell 9" initialValue="9" />
  </CellRow>
</Cells>

Accessibility

Adheres to the Grid WAI-ARIA design pattern . Under the hood, the generated HTML is not a semantic table, but rather a series of divs and inputs with the appropriate ARIA roles, states, and properties .

Keyboard interactions

This component supports a large number of keyboard interactions, with nuances that are specific to spreadsheet-like interactions. It follows the Grid WAI-ARIA design pattern for keyboard interactions (all non-optional interactions) specifically.

Movement & Selection

The following keys can be used to move the selection (the active cell) within the grid of cells.

Key	Action
`ArrowRight`	Moves selection to the next cell in the current row
`ArrowLeft`	Moves selection to the previous cell in the current row
`ArrowUp`	Moves selection to the cell directly above the current cell
`ArrowDown`	Moves selection to the cell directly below the current cell
`Home`	Moves selection to the first cell in the current row
`End`	Moves selection to the last cell in the current row
`PageUp`	Moves selection to the first cell in the current column
`PageDown`	Moves selection to the last cell in the current column
`Tab`	Moves selection to the next cell, wrapping to the next row
`Shift` + `Tab`	Moves selection to the previous cell, wrapping to the previous row
`Ctrl` / `Cmd` + `Space`	Selects all cells in the current column
`Shift` + `Space`	Selects all cells in the current row
`Ctrl` / `Cmd` + `a`	Selects all cells

Editing

The following keys can be used to edit the value of the currently selected (active) cell.

Key	Action
`Backspace` / `Delete`	Deletes the value of the currently selected cell’s input field
`Enter` / `F2`	Toggles focus of the currently selected cell’s input field
`Escape`	Escapes focus of currently selected cell’s input field
`Ctrl` / `Cmd` + `c`	Copies the value of the currently selected cell to the clipboard
`Ctrl` / `Cmd` + `x`	Cuts the value of the currently selected cell to the clipboard
`Ctrl` / `Cmd` + `v`	Pastes the (plain text) value of the currently selected cell from the clipboard

General Modifiers

The following modifiers - keys you hold while pressing other keys - can be used to modify the behavior of the documented keyboard interactions.

Key	Action
`Ctrl`	When `Ctrl` (or `Cmd` on Mac) is held, and any `Arrow` key is then pressed or `MouseDown` event occurs, the focus will change to the furthest cell in the direction of the arrow key.
`Shift`	When `Shift` is held, and any `Arrow` key is then pressed or `MouseDown` event occurs, a selection box will be drawn starting from the currently focused cell, which can be further increased or decreased using the `Arrow` keys, or further `MouseDown` events occur. The focus will not change.
`Shift` + `Ctrl`	When `Shift` and `Ctrl` (or `Cmd` on Mac) are held, and any `Arrow` key is then pressed, a selection box will be drawn starting from the currently focused field, and then the furthest field in the direction of the `Arrow` key pressed. The focus will not change.

Component Reference

Cells

Used to wrap a grid of cells.

CellRow

Used to wrap a row of cells.

Cell

An individual cell within the Cells grid. Contains an input field wrapped in a div container.

Prop	Type	Description
`name`	string	The name of the cell. Required.
`label`	string	The label of the cell. Required.
`initialValue`	string	The initial value of the cell. Required.
`autoActive`	boolean	If `true`, the cell will automatically be activated when the `Cells` component is mounted. Default `false`.