HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
StepsView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA sequence of stages that shows which stage the user is on.StableSince 0.1.0NavigationUsageimport'@fusion.dev/helix/steps'import'@fusion.dev/helix-headless/steps'Preview
API ReferenceStephelix-stepOne stage in a sequence.
PropTypeDescriptioncompletebooleanDefaultfalseWhether this stage is finished.completedLabelstringDefault"{name}, {complete}"What a screen reader hears when the stage is finished while the page is
open. {name} is the stage's name and {complete} is complete-label, so
a language can write the whole sentence in its own order. A stage with no
name says complete-label alone.completeLabelstringDefault"Complete"The words that tell a screen reader the stage is finished. Translate it
with the page.currentbooleanDefaultfalseWhether this is the current stage.disabledbooleanDefaultfalseWhether the stage is disabled, so the user cannot go to it.optionalbooleanDefaultfalseWhether a reader may pass the stage without finishing it, in a sequence
with linear. Ark UI's skippable step.valuestringDefault""The value the step sends in helix-select, and what names the step in its
sequence's active. Without one, the sequence names the step by its place,
counted from 1.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The step's name.contentThe stage's content. The headless tier always renders it, because it has no stylesheet to collapse it with. Your stylesheet decides whether it is collapsed.descriptionA line under the name that describes the stage.markerReplaces the number, or the check a complete step shows.
EventTypeDescriptionhelix-selectHelixSelectEventFired when the step is pressed. Cancelable: cancel it to keep the current step.
MethodTypeDescriptionfocus(options: FocusOptions) => voidPuts focus on the step's name, the control a reader presses, as a
focus() on a native control would.select() => voidFires helix-select for the step, unless the step is disabled or a
linear sequence has it out of reach.
PartDescriptionbodyThe name and its description.contentWhat the stage holds, while it is open.descriptionThe line under the name.labelThe step's name, which is a control.label-buttonThe button inside the label.label-liveThe live region inside that button, rendered only from the first time the button is pending.label-spinnerThe ring that button turns while it is pending.label-textThe words on that button, trimmed to their capitals and baseline.liveThe live region that says a stage was completed, rendered from the first time one is. Visually hidden in the styled tier.markThe glyph inside the marker: a tick, a dot, or an empty ring.markerThe shape carrying the number or the check.stateThe words that describe a finished stage's button. Hidden.
Custom stateDescriptioninvalidThe sequence's validate last answered that this stage is not valid.lockedA linear sequence holds this stage out of reach until the stages before it are finished.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-stepsA sequence of stages that shows which stage the user is on.
PropTypeDescriptionactivestringThe value of the current item.arrowsbooleanDefaultfalseWhether the arrow keys move focus between the stages' names, along the
way the steps run, and the names are one tab stop. Off by default, so the
arrows keep scrolling the page.completion"passed"What marks a stage complete.defaultActivestringDefault""The value of the item declared current in markup.labelstringDefault"Steps"The sequence's name, read by screen readers.linearbooleanDefaultfalseWhether a reader has to finish each stage, or pass an optional one,
before going on to the next.orientation"vertical"Which way the steps run.progressLabelstringDefault"{share, number, percent} complete"What the progress part says to a screen reader. {share, number, percent} writes progress as a percentage the way the locale writes one,
such as 40%, or 40 % in French. {percent} is progress as a whole
number, for a sentence that places the sign itself.validate(step: HelixHeadlessStep) => booleanA function that answers whether a stage is valid, asked about the stage a
reader is on before they move forward from it. Return false to keep them
there. Not asked of an optional stage, nor for a move back.variant"numeric"What each step is marked with.
ReadTypeDescriptionprogressnumberHow far through the sequence is, from 0 to 100: the share of its stages
that are complete, rounded to a whole number.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The steps.
EventTypeDescriptionhelix-activateHelixActivateEventFired after the current step changes, when the element already holds the new step.helix-before-activateHelixBeforeActivateEventFired before the active step changes. Cancelable: cancel it to keep the current step.helix-selectHelixSelectEventFired when a step is pressed. The step dispatches it, and you can listen for it on the sequence. Cancelable: cancel it to keep the current step.
MethodTypeDescriptionnext() => booleanMoves to the next stage that can be gone to, as Ark UI's goToNextStep
does. Returns whether it moved: not past the last stage, not into a stage
linear holds out of reach, and not where a listener refused.previous() => booleanMoves to the stage before, as Ark UI's goToPrevStep does. Returns whether it moved.requestActive(next: string, cause: string) => booleanRequests a new current item, and returns whether the change was applied.reset() => booleanGoes back to the first stage that can be gone to, and clears complete
and the invalid mark from every stage, as Ark UI's resetStep does.
Returns whether it moved: a listener can refuse the move with
helix-before-activate, and the stages then keep their marks.
PartDescriptionprogressHow far through the sequence is, drawn as a bar under the steps once a stylesheet gives the part a display, such as helix-steps::part(progress) { display: block }.
CSS PropertyDescription--steps-complete-colorColor of the mark on a finished step.--steps-connector-colorColor of the line that connects the steps.--steps-connector-insetSpace on either side of a mark, before the connecting line.--steps-current-colorColor of the mark on the current step.--steps-gapSpace between one step and the next.--steps-marker-sizeSize of the mark, whether an icon or a digit.--steps-progressHow far through the sequence is, as a percentage, written on the progress part.--steps-progress-colorFill of the progress bar, once a page shows the progress part.--steps-progress-thicknessHeight of the progress bar.--steps-progress-track-colorColor of the progress bar's track.
Custom stateDescriptioncompleteEvery stage is complete.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Stephelix-headless-stepOne stage in a sequence.
PropTypeDescriptioncompletebooleanDefaultfalseWhether this stage is finished.completedLabelstringDefault"{name}, {complete}"What a screen reader hears when the stage is finished while the page is
open. {name} is the stage's name and {complete} is complete-label, so
a language can write the whole sentence in its own order. A stage with no
name says complete-label alone.completeLabelstringDefault"Complete"The words that tell a screen reader the stage is finished. Translate it
with the page.currentbooleanDefaultfalseWhether this is the current stage.disabledbooleanDefaultfalseWhether the stage is disabled, so the user cannot go to it.optionalbooleanDefaultfalseWhether a reader may pass the stage without finishing it, in a sequence
with linear. Ark UI's skippable step.valuestringDefault""The value the step sends in helix-select, and what names the step in its
sequence's active. Without one, the sequence names the step by its place,
counted from 1.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The step's name.contentThe stage's content. The headless tier always renders it, because it has no stylesheet to collapse it with. Your stylesheet decides whether it is collapsed.descriptionA line under the name that describes the stage.markerReplaces the number, or the check a complete step shows.
EventTypeDescriptionhelix-selectHelixSelectEventFired when the step is pressed. Cancelable: cancel it to keep the current step.
MethodTypeDescriptionfocus(options: FocusOptions) => voidPuts focus on the step's name, the control a reader presses, as a
focus() on a native control would.select() => voidFires helix-select for the step, unless the step is disabled or a
linear sequence has it out of reach.
PartDescriptionbodyThe name and its description.contentWhat the stage holds, while it is open.descriptionThe line under the name.labelThe step's name, which is a control.label-buttonThe button inside the label.label-liveThe live region inside that button, rendered only from the first time the button is pending.label-spinnerThe ring that button turns while it is pending.label-textThe words on that button, trimmed to their capitals and baseline.liveThe live region that says a stage was completed, rendered from the first time one is. Visually hidden in the styled tier.markThe glyph inside the marker: a tick, a dot, or an empty ring.markerThe shape carrying the number or the check.stateThe words that describe a finished stage's button. Hidden.
Custom stateDescriptioninvalidThe sequence's validate last answered that this stage is not valid.lockedA linear sequence holds this stage out of reach until the stages before it are finished.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-stepsA sequence of stages that shows which stage the user is on.
PropTypeDescriptionactivestringThe value of the current item.arrowsbooleanDefaultfalseWhether the arrow keys move focus between the stages' names, along the
way the steps run, and the names are one tab stop. Off by default, so the
arrows keep scrolling the page.completion"passed"What marks a stage complete.defaultActivestringDefault""The value of the item declared current in markup.labelstringDefault"Steps"The sequence's name, read by screen readers.linearbooleanDefaultfalseWhether a reader has to finish each stage, or pass an optional one,
before going on to the next.orientation"vertical"Which way the steps run.progressLabelstringDefault"{share, number, percent} complete"What the progress part says to a screen reader. {share, number, percent} writes progress as a percentage the way the locale writes one,
such as 40%, or 40 % in French. {percent} is progress as a whole
number, for a sentence that places the sign itself.validate(step: HelixHeadlessStep) => booleanA function that answers whether a stage is valid, asked about the stage a
reader is on before they move forward from it. Return false to keep them
there. Not asked of an optional stage, nor for a move back.variant"numeric"What each step is marked with.
ReadTypeDescriptionprogressnumberHow far through the sequence is, from 0 to 100: the share of its stages
that are complete, rounded to a whole number.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The steps.
EventTypeDescriptionhelix-activateHelixActivateEventFired after the current step changes, when the element already holds the new step.helix-before-activateHelixBeforeActivateEventFired before the active step changes. Cancelable: cancel it to keep the current step.helix-selectHelixSelectEventFired when a step is pressed. The step dispatches it, and you can listen for it on the sequence. Cancelable: cancel it to keep the current step.
MethodTypeDescriptionnext() => booleanMoves to the next stage that can be gone to, as Ark UI's goToNextStep
does. Returns whether it moved: not past the last stage, not into a stage
linear holds out of reach, and not where a listener refused.previous() => booleanMoves to the stage before, as Ark UI's goToPrevStep does. Returns whether it moved.requestActive(next: string, cause: string) => booleanRequests a new current stage, and returns whether it moved.reset() => booleanGoes back to the first stage that can be gone to, and clears complete
and the invalid mark from every stage, as Ark UI's resetStep does.
Returns whether it moved: a listener can refuse the move with
helix-before-activate, and the stages then keep their marks.
PartDescriptionprogressHow far through the sequence is, as a progressbar carrying --steps-progress. Hidden until a stylesheet gives it a display.
CSS PropertyDescription--steps-progressHow far through the sequence is, as a percentage, written on the progress part.
Custom stateDescriptioncompleteEvery stage is complete.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionActiveA sequence with the middle step current, showing a finished step and a step still ahead.CollapsibleA vertical sequence where only the current stage shows its content.ControlledA sequence controlled by your code, which handles the event and sets active.EventsA pressed step fires helix-select, and the sequence fires helix-before-activate before it changes.LinearA sequence a reader goes through in order, where an optional step can be passed unfinished.NumericSteps marked with numbers.PreviewA sequence with each step named and its state shown.PreviewA sequence with each step named and its state shown.VerticalA sequence that runs down the page.