Cratis Components stepper command dialogs
StepperCommandDialog splits one command's form across named steps. The
user moves with Previous and Next; Submit appears on the last step once every
field across every step is valid.
Dialog dismissal and refusal
Requires Components 4.36.0 for independent dismissal controls; check yarn why @cratis/components, or use the older dismissable contract.
Dialog and CommandDialog accept independent dismissOnOutsideClick,
closeOnEscape and showCloseButton; each falls back to dismissable. Busy
dialogs cannot be dismissed. The busy confirm remains focusable as
aria-disabled and ignores duplicate activation; a refused confirm restores
focus and announces the provider's refused message. Do not replace it with a
disabled button that loses focus or close the dialog on validation refusal.
Verified product sources
| Package | Verified from |
|---|---|
@cratis/components |
its package manifest, Source/CommandDialog/* (StepperCommandDialog, CommandStepper, StepperPanel), Documentation/StepperCommandDialog/*, Documentation/CommandStepper/* |
@cratis/arc.react |
peer range declared by @cratis/components |
Choose it over CommandDialog when
- the form has too many fields to show at once;
- the fields group into logical stages ("Contact → Details → Budget");
- guided linear input with per-step feedback is what the task deserves.
A four-field form is usually still an ordinary CommandDialog.
Step 1 — One command for the whole wizard
Every step contributes properties to the same command instance. Define the command on the backend and run a Debug build so the TypeScript proxy exists before importing it.
Step 2 — Build the dialog
import { StepperCommandDialog, StepperPanel } from '@cratis/components/CommandDialog';
import { InputTextField, NumberField, TextAreaField } from '@cratis/components/CommandForm';
import { DialogResult, useDialogContext } from '@cratis/arc.react/dialogs';
import { CreateProject } from '../api/Projects/CreateProject';
export const CreateProjectDialog = () => {
const { closeDialog } = useDialogContext();
return (
<StepperCommandDialog<CreateProject>
command={CreateProject}
title='Create new project'
okLabel='Create'
=> closeDialog(DialogResult.Ok)}
=> closeDialog(DialogResult.Cancelled)}>
<StepperPanel header='Contact info'>
<InputTextField<CreateProject> value={c => c.email} title='Contact email' type='email' />
</StepperPanel>
<StepperPanel header='Project details'>
<InputTextField<CreateProject> value={c => c.name} title='Project name' />
<TextAreaField<CreateProject> value={c => c.description} title='Description' rows={4} />
</StepperPanel>
<StepperPanel header='Budget'>
<NumberField<CreateProject> value={c => c.budget} title='Budget' />
</StepperPanel>
</StepperCommandDialog>
);
};
Rules:
- Give every
StepperPanelaheader— the house convention for a named step. Its type is optionalReactNode, not a required string. - All
CommandFormfields inside any panel bind to the same command instance through theirvalueaccessor. - Each command property belongs on exactly one step.
- Next is disabled while the current step has validation errors.
- Submit appears on the last step only when every field across every step is valid.
StepperCommandDialogreads the dialog context when it is hosted byuseDialog, and works standalone when it is not.
Step 3 — Open it from the page
import { useDialog } from '@cratis/arc.react/dialogs';
const [CreateProjectWrapper, showCreateProject] = useDialog(CreateProjectDialog);
<MenuItem label='New project' icon={FaPlus} command={() => showCreateProject()} /> // icon is a component type, e.g. from 'react-icons/fa6'
<CreateProjectWrapper />
Validation timing
Pass validateOnInit to run validation on mount so a wizard opened with
pre-populated invalid values shows its errors immediately instead of after the
first keystroke. validateOn ('blur' | 'change' | 'both') chooses when
subsequent validation runs.
Pre-populating an edit wizard
initialValues is the synchronous baseline and also the change-tracking
baseline — use it for values that must be present but are not user-entered.
currentValues is the reactive overlay for values that arrive late, such as
from a query.
<StepperCommandDialog
command={UpdateProject}
title='Update project'
initialValues={{ projectId: project.id }}
currentValues={{ name: project.name, description: project.description }}>
Never seed a value required for validity in onBeforeExecute — validation runs
against the pre-transform values, so the Submit button would stay permanently
disabled.
Orientation and labels
<StepperCommandDialog
command={RegisterEmployee}
title='Register employee'
orientation='vertical'
okLabel='Register'
nextLabel='Continue'
previousLabel='Back'>
Props
Dialog-level props:
| Prop | Type | Default |
|---|---|---|
command |
the generated command class | required |
title |
string |
required |
children |
StepperPanel elements |
— |
visible |
boolean |
true |
width |
string |
'600px' |
okLabel |
string |
'Submit' |
nextLabel |
string |
'Next' |
previousLabel |
string |
'Previous' |
showCancel |
boolean |
false |
cancelLabel |
string |
'Cancel' |
isValid |
boolean |
extra validity gate on top of form validity |
onConfirm / onCancel / onClose |
close gates | — |
onBeforeExecute |
(values) => values |
transformer; must return the values |
confirmBeforeExecute |
(values) => boolean | Promise<boolean> |
after validation and transformation; only true executes |
style / contentStyle |
CSSProperties |
— |
resizable |
boolean |
false — accepted but has no effect |
Stepper-level props (inherited from the stepper customization surface):
| Prop | Type | Default |
|---|---|---|
orientation |
'horizontal' | 'vertical' |
'horizontal' |
headerPosition |
'top' | 'bottom' |
'top' |
linear |
boolean |
true |
start / end |
React.ReactNode |
extra content beside the step headers |
onChangeStep |
(event: { index: number }) => void |
once per accepted move: header, Previous, Next |
Command-form props (initialValues, currentValues, validateOn,
validateOnInit, onSuccess, onValidationFailure, onFailed,
autoServerValidate, …) all apply as well. Horizontal steppers (Requires Components 4.26.3) show names below
numbers and wrap. Panels are named by their headers through
aria-labelledby; custom header ids are preserved.
While confirmBeforeExecute is pending, fields are disabled; changed command
values discard approval and skip execution. Confirm the new values again.
Two part targets
The inherited pt (StepperParts: root, list, step, header, number,
title, separator, panels, panel) targets the inner stepper. Use
dialogPt (DialogParts) and dialogClassName to reach the outer dialog.
Getting these the wrong way round is the usual cause of a pt that appears to do
nothing. (ptOptions/unstyled are compatibility no-ops;
dialogPtOptions/dialogUnstyled are also deprecated no-ops.)
Dismissal while the command runs
The dialog withdraws its close control, Escape, and backdrop dismissal while the
command is executing, so a half-submitted wizard cannot be abandoned mid-flight.
Do not add your own Cancel button to the footer — set showCancel if the wizard
needs one.
Related components
CommandStepper (same subpath) is the stepper without the dialog chrome, for
embedding a wizard directly in a page. It takes the same StepperPanel
children. It reports onException, onUnauthorized, and onFailed (including
validation failures), and guards against double submission.
Common mistakes
| Mistake | Fix |
|---|---|
| A hand-rolled Cancel button in the footer | Set showCancel, or rely on the header close control |
| One step per field | Group related fields; aim for two to five per step |
| The same property bound on two steps | Each property appears on exactly one step |
A StepperPanel without header |
header is the navigation label |
| Several panels wrapped in one fragment | A fragment counts as one step — give each step its own StepperPanel child |
A raw control (TextInput, a native <input>) for a command value |
Use a CommandForm field, or the value is never bound and validation never re-runs |
Seeding a required value in onBeforeExecute |
Use initialValues |
pt applied expecting it to reach the dialog |
pt targets the stepper; use dialogPt |
Route near misses
- An accepted
.playmodel under the model root covers the behavior, or the repository is opted in (pergeneral.md"Model first"; wherecratis-screenplay-modeling-lifecycleis installed, run itsscripts/model-first-status.mjs): change the model first withcratis-screenplay-event-modeling. If the Screenplay skills are not installed, say so and do not author.playfrom memory. Edit code here only for infrastructure, clients, adapters, Screenplay code attachments, or gap-fill scope (cratis-screenplay-render-and-gap-fill); never edit Stage-managed output.
Verify
- Imports come from
@cratis/components/CommandDialogand@cratis/components/CommandForm, not the root barrel. - Every
StepperPanelhas aheaderand is a direct child. - Every command property appears on exactly one step.
- Required values come from
initialValues. onBeforeExecute, if present, returns the values.- Pass-through props target the intended element.
- Lint and the TypeScript build pass.