Stage field

A React component in Beamline's Form controls category.

A record's status as its stages in order, editable in place. Stages before the current one read as passed (gone through, never "complete"); only the moves allowed from here are pressable, and pressing another says why not in words beside the field; a move reads as saving until it's saved and snaps back with the reason when refused. Without room for the row, the stages become a full labelled list rather than truncated steps.

Use it for

A record's status that moves through stages with rules (a request, a deal, a ticket, an application).
Anywhere a move must be allowed or refused with a reason, and saved before it reads as done.

Not for

Where someone is in a multi-step form (stepper).
Picking one of a few equal options (segmented-control).

Anatomy

stages: each with its number or a check, its name and its word (passed, current, move here, not from here, saving)
said: the reason a move isn't allowed, the move saved, or the refusal

States

stage: passed (success tint), current (accent), allowed (pressable outline), not allowed (quiet, pressing says why), saving (info tint)
move: saving; saved (said); refused (snaps back, the reason said)
layout: row; list when there is no room or chosen
disabled: every stage said, nothing pressable
right to left: the order mirrors
reduced motion: no tint transitions

Keyboard

Tab to each stage; Enter or Space moves there when allowed, or says why not

Motion

Tints ease between states over the standard duration. Nothing runs at rest.

Props

Prop	Type	Default	Description
`label` (required)	`string`	—	The field's name ("Status"), its accessible name.
`stages` (required)	`Stage[]`	—
`value`	`string`	—	Controlled selected value; omit to use defaultValue.
`defaultValue`	`string`	—	Initial selection when uncontrolled; omitted by default.
`canMove`	`((to: string, from: string) => string \| true)`	—	Whether a record may move from `from` to `to`: true, or the reason it can't ("needs an approver").
`onChange`	`((to: string, from: string) => void \| Promise<unknown>)`	—	Save the move; the stage reads as saving until it resolves; reject with the reason to snap back.
`layout`	`"auto" \| "list" \| "row"`	—	"auto": a row, or a labelled list when there is no room; "row" or "list" to choose.
`disabled`	`boolean`	—
`labels`	`Partial<{ passed: Message; current: Message; next: Message; saving: Message; notAllowed…`	—
`className`	`string`	—	Classes on the documented visual root; no override by default.
`style`	`CSSProperties`	—	Inline styles on the documented visual root; no overrides by default.
`ref`	`Ref<HTMLDivElement>`	—	Receives the documented native target or imperative handle; omitted by default.

Built from

Dependencies

lucide-react

Import

import { StageField } from "@beamline/stage-field";

Get it

Stage field is part of Beamline UI. Install the parts you need in your React app as compiled packages or editable source. Get Beamline · Connect your agent