ScanGrid

ScanGrid is the grid a hunt happens on, and the scan that finds things in it. On its own it draws cells in five levels of a theme's ramp. Through its handle, seek hunts one cell down and hands back what a CardOpening needs to send a card out of it.

Nothing found yet

The grid alone. Press Scan to hunt a cell down.

Usage

tsx

import { ScanGrid, type ScanGridHandle } from "@react-cards-opening/ui";

const scan = useRef<ScanGridHandle>(null);
const [veiled, setVeiled] = useState(true);

<ScanGrid handle={scan} levels={levels} veiled={veiled} onUnveil={() => setVeiled(false)} />;

With CardOpening

seek returns { element, lead, release }, which is exactly what launch on CardOpening takes. The card waits for the scan, then lifts out of the cell.

tsx

<CardOpening
  opening={hunt.opening}
  launch={(card, show) => scan.current?.seek(cellOf(card), show) ?? null}
/>

Props

Prop	Type	What it does
`levels`	`readonly number[]`	One number per cell, 0 (unlit) to 4. Cells fill top to bottom, then left to right.
`lead?`	`number`	Empty slots before the first cell.
`rows?`	`number`	Cells in a column. 7 by default.
`theme?`	`CardTheme`	The colours.
`tone?`	`string`	The colour of the lock and the crack: the hunted card's tier.
`veiled?`	`boolean`	Blank until the beam has passed.
`onUnveil?`	`() => void`	The beam finished its first pass. Stop veiling.
`idle?`	`boolean`	Nothing is being hunted: the grid may twitch and sparkle.
`markers?`	`ReadonlyMap<number, ScanMarker>`	Found cells by index: `{ id, name, colour }`.
`onMarkerPress?`	`(marker, element) => void`	A found cell was pressed.
`markersDisabled?`	`boolean`	Found cells cannot be pressed for now.
`markerLabel?`	`(name: string) => string`	What a screen reader calls a found cell.
`handle?`	`Ref<ScanGridHandle>`	Where `seek`, `reset` and `cell` are handed out.
`className?`	`string`	Added to the grid's root.
`classNames?`	`ScanGridClassNames`	A class of your own for each part of the grid.
`style?`	`CSSProperties`	Added to the grid's root.

The handle

Method	What it does
`seek(cell, show, options?)`	Hunts the cell down and returns `{ element, lead, release }`, or null when the grid has no such cell. `options.onLock` fires when the beam settles; `options.flash` is an element to flash on a loud find.
`reset()`	Forgets which cells the beam has lit, so a veiled grid is blank again.
`cell(index)`	The element of a cell.

Blank until scanned

A veiled grid shows every cell as unlit until the beam has crossed it. The first seek on a veiled grid sweeps the whole width, and onUnveil fires when it is done. While veiled and idle, a few cells shift by a pixel now and then: something is in there.

Other shapes

tsx

// A board: five rows, twelve columns.
<ScanGrid levels={board} rows={5} />

// A calendar whose first day is a Wednesday.
<ScanGrid levels={year} lead={3} />

Last updated 2026-10-11. Read this page as Markdown.