For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt, and this page is available as Markdown at https://rickyshin93.github.io/tao-ui/components/steps.md.
v0.0.57
  • English
  • Steps

    Navigation@rockshin/tao-ui

    Guides users through the ordered stages of a task.

    When to use

    Use Steps when the work has a sequence — a checkout flow, an onboarding wizard, a deployment pipeline. Steps also doubles as a progress indicator for a process the user is watching rather than driving.

    Recommended

    • Keep titles to one or two words; move detail into content.
    • Drive the whole bar from current and let the status be derived from position.
    • Provide onChange when revisiting an already completed step is meaningful.
    • Switch to orientation="vertical" for long flows or narrow layouts.

    Avoid

    • Do not use Steps for peer views at the same level; use Tabs.
    • Do not use Steps for a single indeterminate operation; use Spinner.
    • Do not set status per item unless a step genuinely failed or was skipped.

    Examples

    Basic usage

    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    TSX

    Vertical and clickable

    onChange receives the absolute step index. Clicking the current step is a no-op, and disabled items never become interactive.

    1
    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    4
    Locked
    Unavailable.
    1
    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    4
    Locked
    Unavailable.
    TSX

    Status, variants, and sizes

    status sets the state of the current step; every other step derives its own state from position. variant picks a solid or outlined icon treatment and size switches density.

    Finished
    This step is done.
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    TSX

    Types

    type changes the whole shape of the bar: dot replaces numbered icons with small dots, navigation turns each step into a clickable tab with an underline, and panel renders steps as contiguous notched panels.

    One
    First step
    Two
    Second step
    Three
    Third step
    One
    First step
    2
    Two
    Second step
    3
    Three
    Third step
    One
    First step
    2
    Two
    Second step
    3
    Three
    Third step
    One
    First step
    2
    Two
    Second step
    3
    Three
    Third step
    TSX

    Inline

    type="inline" renders a compact dot strip whose descriptions live in tooltips. offset shifts the strip along its axis and titlePlacement moves the label under the dot.

    One
    First step
    Two
    Second step
    Three
    Third step
    One
    First step
    Two
    Second step
    Three
    Third step
    TSX

    Progress and max count

    percent draws a progress ring around the current icon. maxCount collapses long flows, folding the hidden range into a disabled ellipsis step while onChange keeps reporting the original indexes.

    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    Step 1
    Step 3
    4
    Step 4
    5
    Step 5
    10
    Step 10
    TSX

    Custom icons

    items[].icon replaces a single step's glyph. iconRender replaces every glyph and receives the step index, the active flag, and an Icon component that renders the semantic icon container.

    1
    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    TSX

    Semantic DOM styling

    Every part of a step is addressable through classNames and styles, and each item can override its own parts. Use finishIconBackground and finishIconColor to set the built-in finished circle background and check color independently for default, navigation, and panel steps. Dot steps and custom icons are unaffected.

    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    TSX

    Clickable steps

    Maintain current with onChange and update the displayed content after a step changes.

    1
    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.

    current: 0

    TSX

    Current step error

    status="error" marks the current step as failed; explain the cause in adjacent content.

    Finished
    This step is done.
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    TSX

    Per-step status

    Set status per item for workflows that combine completed, failed, and waiting steps.

    Done
    Finished.
    Failed
    Something broke.
    3
    Running
    In progress.
    4
    Queued
    Not started.
    TSX

    Title placement

    Choose where titles sit relative to step indicators to suit the available space.

    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    TSX

    Progress within a step

    Use percent for progress within the current step and change it in this example.

    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.

    percent: 40

    TSX

    Dot steps

    type="dot" uses compact nodes for tracking status.

    Finished
    This step is done.
    In Progress
    Working on it now.
    Waiting
    Not started yet.
    TSX

    Custom step dots

    Customize step dots with a render callback while retaining titles and status.

    Finished
    This step is done.
    In Progress
    Working on it now.
    Waiting
    Not started yet.
    TSX

    Navigation steps support switching between stages of a workflow.

    1
    Step 1
    First
    2
    Step 2
    Second
    3
    Step 3
    Third
    TSX

    Panel steps

    Panel steps provide a larger area for titles, descriptions, and interaction.

    One
    2
    Two
    3
    Three
    4
    Four
    One
    2
    Two
    3
    Three
    4
    Four
    TSX

    Limit visible steps

    Use maxCount for a long workflow and observe how the visible range follows the current step.

    Step 1
    Step 3
    4
    Step 4
    5
    Step 5
    10
    Step 10
    TSX

    Disabled steps

    Disable unavailable steps without disabling navigation to the others.

    First
    2
    Second
    3
    Locked
    TSX

    Long title ellipsis

    Truncate long titles in constrained space and put detail in step content.

    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    1
    A rather long first title
    with a subtitle
    And a long description that will be truncated.
    2
    Second
    Also truncated when needed.
    TSX

    Initial step number

    Use initial to offset displayed numbers while keeping the component index contract for current.

    Finished
    This step is done.
    4
    In Progress
    Working on it now.
    5
    Waiting
    Not started yet.
    TSX

    Inherit provider settings

    Inherit size and appearance settings and override them on an individual Steps instance.

    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    TSX

    API

    Steps

    PropertyDescriptionTypeDefault Value
    itemsStep data.StepItem[] | undefined-
    currentCurrent step, counted from 0. Overridden per step by items.status.number | undefined-
    initialNumbering offset — the first step is numbered initial + 1.number | undefined-
    statusStatus of the current step; the others derive theirs from position.StepsStatus | undefinedprocess
    orientationLayout axis.StepsOrientation | undefined-
    titlePlacementWhere the title sits relative to the icon.StepsTitlePlacement | undefined-
    responsiveCollapse to vertical below 576px.boolean | undefinedtrue
    sizeVisual density.StepsSize | undefined-
    variantStyle variant.StepsVariant | undefinedfilled
    typeSteps flavour.StepsType | undefined-
    percentProgress ring on the process icon; ignored by type="inline".number | undefined-
    maxCountCollapse to at most N steps (>= 3); hidden ranges become an ellipsis step.number | undefined-
    offsetLeading flex offset for type="inline".number | undefined-
    ellipsisTruncate overflowing titles, subtitles, and content.boolean | undefined-
    iconRenderReplace the icon node of every step.StepsIconRender | undefined-
    finishIconBackgroundBackground of the built-in finished-step circle.BackgroundColor | undefined-
    finishIconColorColor of the built-in finished-step check mark.Color | undefined-
    onChangeFires with the absolute step index when a non-current step is activated.((current: number) => void) | undefined-
    classNameAdditional css classstring | undefined-
    styleAdditional styleCSSProperties | undefined-