Theme
Version
GitHub PyPI Discord
On this page

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

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

Set interactive to render form-safe native Buttons. Linear mode permits the current and completed Steps while future Steps remain unavailable.

Navigate completed Steps
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

Navigate Steps in any order
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 optional and error Steps
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.

Control active workflow state
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

Compare Stepper presentation
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.

Customize Stepper
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(...).

InputTypeDefaultEffect
labelstrrequiredSupplies the accessible navigation landmark name.
activeint0Sets the zero-based initial active Step.
interactiveboolFalseStructurally renders eligible Step triggers as native Buttons.
linearboolTrueMakes upcoming interactive Steps unavailable.
disabledboolFalseDisables 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)NoneAdds root classes.
styleCStyleValue | None (CStyleValue)NoneAdds root inline styles.
attrsMapping[str, object] | NoneNoneAdds 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 />.

InputTypeOmitted behaviorEffect
activeint | nullUses uncontrolled committed state.Controls the zero-based active Step; null releases control.
linearboolUses the server value.Reactively limits navigation to current and completed Steps.
disabledboolUses 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) | undefinedNo 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(...).

InputTypeDefaultEffect
disabledboolFalseMakes this Step unavailable when interactive.
optionalboolFalseReflects optional workflow metadata.
errorboolFalseReflects an application-owned error state.
class_CClassValue | None (CClassValue)NoneAdds classes to the concrete Step list item.
styleCStyleValue | None (CStyleValue)NoneAdds inline styles to the concrete Step list item.
attrsMapping[str, object] | NoneNoneAdds 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

SlotRequiredDataFallback
defaultyes{} (CStepperDefaultSlotData)None. Requires at least two direct CStep declarations.

CStep slots

SlotRequiredDataFallback
defaultyes{index, state, is_current, is_disabled} (CStepDefaultSlotData)None. Supplies the Step label.
descriptionno{index, state, is_current, is_disabled} (CStepDescriptionSlotData)Omitted.
indicatorno{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

EventSignatureTrigger and timingDetailControlled 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.

VariableTypePurposeDefault
--cui-stepper-gaplengthGap between Steps.sm: 0.5rem; md: 0.75rem; lg: 1rem
--cui-stepper-indicator-sizelengthIndicator inline and block size.sm: 1.625rem; md: 2rem; lg: 2.5rem
--cui-stepper-trigger-gaplengthGap between indicator and copy.0.625rem
--cui-stepper-radiuslengthRoot and trigger corner radius input.0.75rem
--cui-stepper-active-colorcolorCurrent indicator color.light #175cd3; dark #93c5fd
--cui-stepper-complete-colorcolorCompleted indicator color.light #067647; dark #6ce9a6
--cui-stepper-muted-colorcolorUpcoming indicator and description color.light #667085; dark #a4a7ae
--cui-stepper-backgroundcolorRoot background.plain and outline transparent; soft subtle CanvasText mix
--cui-stepper-border-colorcolorOutline indicator and separator color.light #d0d5dd; dark #535862
--cui-stepper-focus-colorcolorInteractive 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

AttributeElementTypeMeaning
aria-labelRoot navstringNames the workflow navigation landmark.
data-activeRoot navnonnegative-integer-stringMirrors effective active index.
data-orientationRoot navhorizontal | verticalMirrors effective layout.
data-interactiveRoot navpresent-or-absentPresent when Steps render native Button triggers.
data-linearRoot navpresent-or-absentPresent when upcoming Steps are unavailable.
data-variantRoot navplain | soft | outlineMirrors effective surface treatment.
data-sizeRoot navsm | md | lgMirrors effective geometry.
data-indexStep linonnegative-integer-stringExposes zero-based settled order.
data-stateStep licomplete | current | upcomingMirrors derived status.
aria-currentCurrent triggerstepIdentifies the current workflow Step.
data-disabledRoot or Steppresent-or-absentReflects effective component or Step unavailability.
data-optionalStep lipresent-or-absentReflects optional metadata.
data-errorStep lipresent-or-absentReflects error metadata.

Selectors

Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.

CStepper selectors

SelectorElementPurpose
[data-citry-ui-part="stepper"]Root navStable root and attrs destination.
[data-citry-ui-part="list"]Ordered listStable Step collection.
[data-citry-ui-part="step"]Step list itemStable declaration attrs destination and state surface.
[data-citry-ui-part="trigger"]Button or spanStable interactive or static Step surface.
[data-citry-ui-part="indicator"]Decorative spanStable Step marker.
[data-citry-ui-part="copy"]Copy wrapper spanStable label and description wrapper.
[data-citry-ui-part="label"]Label spanStable accessible label content.
[data-citry-ui-part="description"]Optional description spanStable described-by target.
[data-citry-ui-part="separator"]Decorative spanStable connector.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

InterfaceDefinition
CClassValuestr | Mapping[str, bool] | Sequence[CClassValue]
CStyleValuestr | Mapping[str, object] | Sequence[CStyleValue]
CStepperOrientationLiteral["horizontal", "vertical"]
CStepperVariantLiteral["plain", "soft", "outline"]
CStepperSizeLiteral["sm", "md", "lg"]
CStepStateLiteral["complete", "current", "upcoming"]
CStepDescriptionSlotDataCStepDefaultSlotData
CStepIndicatorSlotDataCStepDefaultSlotData

CStepperDefaultSlotData

Empty dataclass: {}.

CStepDefaultSlotData

FieldTypeDefaultMeaning
indexint-Zero-based settled Step index.
state"complete" | "current" | "upcoming" (CStepState)-Server-rendered status.
is_currentbool-Whether this Step is initially current.
is_disabledbool-Whether this Step is initially unavailable.

CStepperActiveChangeDetail

FieldTypeDefaultMeaning
activeint-Requested zero-based index.
previousActiveint-Prior effective index.
controlledbool-Whether a client active value currently controls state.
stepHTMLElement-Activated Step list item.
sourceEventEvent-Native click event.

Translation keys

-