Stepper
Use CStepper for the progress and navigation surface of a finite workflow. Compose the current panel, validation, and Previous/Next actions beside it so application state has one owner.
Stepper at a glance
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class StepperAtAGlance(Component):
template = """
<c-CStepper label="Account setup" c-active="1" variant="soft">
<c-CStep>Profile</c-CStep>
<c-CStep>Security</c-CStep>
<c-CStep>Review</c-CStep>
</c-CStepper>
"""
preview = StepperAtAGlance()
preview # noqa: B018
Navigate a linear workflow
Set interactive to render form-safe native Buttons. Linear mode permits the current and completed Steps while future Steps remain unavailable.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class InteractiveStepper(Component):
template = """
<section x-data="{ active: 1 }">
<c-CStepper
label="Publication workflow"
c-active="1"
interactive
$c-props="{ active, onActiveChange: (next) => active = next }"
>
<c-CStep>Draft</c-CStep>
<c-CStep>Review</c-CStep>
<c-CStep>Publish</c-CStep>
</c-CStepper>
<p>Current zero-based index: <strong x-text="active"></strong></p>
</section>
"""
preview = InteractiveStepper()
preview # noqa: B018
Allow non-linear navigation
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class NonlinearStepper(Component):
template = """
<section x-data="{ active: 0 }">
<c-CStepper
label="Profile sections"
interactive
c-linear="False"
$c-props="{ active, onActiveChange: (next) => active = next }"
>
<c-CStep>Identity</c-CStep>
<c-CStep>Preferences</c-CStep>
<c-CStep>Notifications</c-CStep>
</c-CStepper>
</section>
"""
preview = NonlinearStepper()
preview # noqa: B018
Show workflow metadata
Optional descriptions and error state belong to each Step declaration.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class StepperStates(Component):
template = """
<c-CStepper label="Checkout" c-active="1" orientation="vertical" variant="outline">
<c-CStep>
<c-fill name="default">Delivery address</c-fill>
<c-fill name="description">Saved</c-fill>
</c-CStep>
<c-CStep error>
<c-fill name="default">Payment</c-fill>
<c-fill name="description">Check the card number</c-fill>
</c-CStep>
<c-CStep optional>
<c-fill name="default">Gift message</c-fill>
<c-fill name="description">Optional</c-fill>
</c-CStep>
</c-CStepper>
"""
preview = StepperStates()
preview # noqa: B018
Control the active Step
Client active is controlled while supplied. onActiveChange requests a new zero-based index; the application decides whether to accept it.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ControlledStepper(Component):
template = """
<section x-data="{ active: 0 }">
<c-CStepper
label="Workspace setup"
interactive
c-linear="False"
$c-props="{ active, onActiveChange: (next) => active = next }"
>
<c-CStep>Workspace</c-CStep>
<c-CStep>Members</c-CStep>
<c-CStep>Permissions</c-CStep>
</c-CStepper>
<c-CGroup>
<c-CButton @click="active = Math.max(0, active - 1)">Previous</c-CButton>
<c-CButton @click="active = Math.min(2, active + 1)">Next</c-CButton>
</c-CGroup>
</section>
"""
preview = ControlledStepper()
preview # noqa: B018
Compare orientation, size, and variant
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class StepperPresentation(Component):
template = """
<c-CStack>
<c-CStepper label="Small plain" size="sm">
<c-CStep>Start</c-CStep><c-CStep>Finish</c-CStep>
</c-CStepper>
<c-CStepper label="Medium soft" variant="soft" c-active="1">
<c-CStep>Start</c-CStep><c-CStep>Finish</c-CStep>
</c-CStepper>
<c-CStepper label="Large vertical outline" orientation="vertical" variant="outline" size="lg">
<c-CStep>Start</c-CStep><c-CStep>Finish</c-CStep>
</c-CStepper>
</c-CStack>
"""
preview = StepperPresentation()
preview # noqa: B018
Customize Stepper
Public variables and part selectors work from an ancestor or the Stepper root.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class CustomizedStepper(Component):
css = """
.orchid-stepper {
--cui-stepper-active-color: #7f56d9;
--cui-stepper-complete-color: #039855;
--cui-stepper-radius: 1.25rem;
}
.orchid-stepper [data-citry-ui-part="label"] { letter-spacing: 0.02em; }
"""
template = """
<c-CStepper label="Orchid order" c-active="1" variant="outline" class_="orchid-stepper">
<c-CStep>Choose</c-CStep><c-CStep>Prepare</c-CStep><c-CStep>Deliver</c-CStep>
</c-CStepper>
"""
preview = CustomizedStepper()
preview # noqa: B018
Accessibility and behavior
The root is a named navigation landmark with an ordered list. The current Step uses aria-current="step". Interactive Steps are ordinary button type="button" controls, so Tab, Enter, Space, focus, disabledness, and form safety remain native. Stepper does not implement a composite Arrow-key model and does not render workflow panels.
API reference
Inputs
CStepper server inputs
Server inputs are passed in a template through <c-CStepper ... /> or in Python through CStepper(...).
| Input | Type | Default | Effect |
|---|---|---|---|
label | str | required | Supplies the accessible navigation landmark name. |
active | int | 0 | Sets the zero-based initial active Step. |
interactive | bool | False | Structurally renders eligible Step triggers as native Buttons. |
linear | bool | True | Makes upcoming interactive Steps unavailable. |
disabled | bool | False | Disables every interactive Step. |
orientation | "horizontal" | "vertical" (CStepperOrientation) | "horizontal" | Selects logical Step layout. |
variant | "plain" | "soft" | "outline" (CStepperVariant) | "plain" | Selects surface treatment. |
size | "sm" | "md" | "lg" (CStepperSize) | "md" | Selects indicator and spacing geometry. |
class_ | CClassValue | None (CClassValue) | None | Adds root classes. |
style | CStyleValue | None (CStyleValue) | None | Adds root inline styles. |
attrs | Mapping[str, object] | None | None | Adds trusted root attributes without replacing owned semantics state visibility children or runtime. |
CStepper client inputs
Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CStepper />.
| Input | Type | Omitted behavior | Effect |
|---|---|---|---|
active | int | null | Uses uncontrolled committed state. | Controls the zero-based active Step; null releases control. |
linear | bool | Uses the server value. | Reactively limits navigation to current and completed Steps. |
disabled | bool | Uses the server value. | Reactively disables interactive Steps. |
orientation | "horizontal" | "vertical" (CStepperOrientation) | Uses the server value. | Reactively changes logical layout. |
variant | "plain" | "soft" | "outline" (CStepperVariant) | Uses the server value. | Reactively changes surface treatment. |
size | "sm" | "md" | "lg" (CStepperSize) | Uses the server value. | Reactively changes geometry. |
onActiveChange | ((active: number, detail: CStepperActiveChangeDetail) => void) | undefined | No component callback runs. | Receives eligible different Step navigation requests. |
CStep server inputs
Server inputs are passed in a template through <c-CStep ... /> or in Python through CStep(...).
| Input | Type | Default | Effect |
|---|---|---|---|
disabled | bool | False | Makes this Step unavailable when interactive. |
optional | bool | False | Reflects optional workflow metadata. |
error | bool | False | Reflects an application-owned error state. |
class_ | CClassValue | None (CClassValue) | None | Adds classes to the concrete Step list item. |
style | CStyleValue | None (CStyleValue) | None | Adds inline styles to the concrete Step list item. |
attrs | Mapping[str, object] | None | None | Adds trusted list-item attributes without replacing owned identity state or trigger behavior. |
Slots
Slots are passed as nested content or <c-fill> tags in a template, or through the slots={...} argument in Python.
CStepper slots
| Slot | Required | Data | Fallback |
|---|---|---|---|
default | yes | {} (CStepperDefaultSlotData) | None. Requires at least two direct CStep declarations. |
CStep slots
| Slot | Required | Data | Fallback |
|---|---|---|---|
default | yes | {index, state, is_current, is_disabled} (CStepDefaultSlotData) | None. Supplies the Step label. |
description | no | {index, state, is_current, is_disabled} (CStepDescriptionSlotData) | Omitted. |
indicator | no | {index, state, is_current, is_disabled} (CStepIndicatorSlotData) | One-based ASCII Step number. |
Events
Component events are callback inputs supplied through $c-props. Native browser events remain available through Alpine @... attributes.
CStepper events
| Event | Signature | Trigger and timing | Detail | Controlled and cancellation behavior |
|---|---|---|---|---|
onActiveChange | (active: number, detail: CStepperActiveChangeDetail) => void (CStepperActiveChangeDetail) | Eligible different Step activation. | {active, previousActive, controlled, step, sourceEvent} (CStepperActiveChangeDetail) | Requests navigation before an uncontrolled commit or controlled reconciliation. |
Methods
-
CSS
CSS variables to theme the components. Set them on an ancestor or the component itself.
CStepper CSS variables
Apply these variables to CStepper or one of its ancestors.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-stepper-gap | length | Gap between Steps. | sm: 0.5rem; md: 0.75rem; lg: 1rem |
--cui-stepper-indicator-size | length | Indicator inline and block size. | sm: 1.625rem; md: 2rem; lg: 2.5rem |
--cui-stepper-trigger-gap | length | Gap between indicator and copy. | 0.625rem |
--cui-stepper-radius | length | Root and trigger corner radius input. | 0.75rem |
--cui-stepper-active-color | color | Current indicator color. | light #175cd3; dark #93c5fd |
--cui-stepper-complete-color | color | Completed indicator color. | light #067647; dark #6ce9a6 |
--cui-stepper-muted-color | color | Upcoming indicator and description color. | light #667085; dark #a4a7ae |
--cui-stepper-background | color | Root background. | plain and outline transparent; soft subtle CanvasText mix |
--cui-stepper-border-color | color | Outline indicator and separator color. | light #d0d5dd; dark #535862 |
--cui-stepper-focus-color | color | Interactive trigger focus outline. | Highlight |
Attributes
HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.
CStepper attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
aria-label | Root nav | string | Names the workflow navigation landmark. |
data-active | Root nav | nonnegative-integer-string | Mirrors effective active index. |
data-orientation | Root nav | horizontal | vertical | Mirrors effective layout. |
data-interactive | Root nav | present-or-absent | Present when Steps render native Button triggers. |
data-linear | Root nav | present-or-absent | Present when upcoming Steps are unavailable. |
data-variant | Root nav | plain | soft | outline | Mirrors effective surface treatment. |
data-size | Root nav | sm | md | lg | Mirrors effective geometry. |
data-index | Step li | nonnegative-integer-string | Exposes zero-based settled order. |
data-state | Step li | complete | current | upcoming | Mirrors derived status. |
aria-current | Current trigger | step | Identifies the current workflow Step. |
data-disabled | Root or Step | present-or-absent | Reflects effective component or Step unavailability. |
data-optional | Step li | present-or-absent | Reflects optional metadata. |
data-error | Step li | present-or-absent | Reflects error metadata. |
Selectors
Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.
CStepper selectors
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="stepper"] | Root nav | Stable root and attrs destination. |
[data-citry-ui-part="list"] | Ordered list | Stable Step collection. |
[data-citry-ui-part="step"] | Step list item | Stable declaration attrs destination and state surface. |
[data-citry-ui-part="trigger"] | Button or span | Stable interactive or static Step surface. |
[data-citry-ui-part="indicator"] | Decorative span | Stable Step marker. |
[data-citry-ui-part="copy"] | Copy wrapper span | Stable label and description wrapper. |
[data-citry-ui-part="label"] | Label span | Stable accessible label content. |
[data-citry-ui-part="description"] | Optional description span | Stable described-by target. |
[data-citry-ui-part="separator"] | Decorative span | Stable connector. |
Interfaces
Aliases and data shapes referenced above.
Input type aliases
| Interface | Definition |
|---|---|
CClassValue | str | Mapping[str, bool] | Sequence[CClassValue] |
CStyleValue | str | Mapping[str, object] | Sequence[CStyleValue] |
CStepperOrientation | Literal["horizontal", "vertical"] |
CStepperVariant | Literal["plain", "soft", "outline"] |
CStepperSize | Literal["sm", "md", "lg"] |
CStepState | Literal["complete", "current", "upcoming"] |
CStepDescriptionSlotData | CStepDefaultSlotData |
CStepIndicatorSlotData | CStepDefaultSlotData |
CStepperDefaultSlotData
Empty dataclass: {}.
CStepDefaultSlotData
| Field | Type | Default | Meaning |
|---|---|---|---|
index | int | - | Zero-based settled Step index. |
state | "complete" | "current" | "upcoming" (CStepState) | - | Server-rendered status. |
is_current | bool | - | Whether this Step is initially current. |
is_disabled | bool | - | Whether this Step is initially unavailable. |
CStepperActiveChangeDetail
| Field | Type | Default | Meaning |
|---|---|---|---|
active | int | - | Requested zero-based index. |
previousActive | int | - | Prior effective index. |
controlled | bool | - | Whether a client active value currently controls state. |
step | HTMLElement | - | Activated Step list item. |
sourceEvent | Event | - | Native click event. |
Translation keys
-