Steps

TuiSteps is a navigation bar used to guide users through a process to complete tasks. It clearly displays the progress of the current task, completed steps, and subsequent pending items. It supports rich appearance customization and status management.

Basic Usage

Data Mode

This is the most concise usage. Pass an array of step configurations through the options attribute without manually writing the DOM structure.

<script setup>
import { ref } from 'vue';

const activeStep = ref(0);

const stepsData = [
  { title: 'Step 1', description: 'Complete basic information', icon: 'tui-icon ti-user' },
  { title: 'Step 2', description: 'Upload relevant attachments' },
  { title: 'Step 3', description: 'Wait for review results' }
];

const next = () => {
  if (activeStep.value++ > 2) activeStep.value = 0;
};
</script>

<template>
  <TuiSteps :active="activeStep" :options="stepsData" />
  <TuiButton @click="next">Next Step</TuiButton>
</template>

Slot Mode

Use the <TuiStep> sub-component for construction. This method provides higher flexibility and is suitable for scenarios where individual steps require special processing.

<template>
  <TuiSteps :active="1">
    <TuiStep title="Finished" description="This step has ended" />
    <TuiStep title="In Progress" description="Currently processing..." />
    <TuiStep title="Pending" icon="tui-icon ti-settings" />
  </TuiSteps>
</template>

Vertical Layout

Set direction="vertical" to enable the vertical step bar.

Note

In vertical mode, it is usually necessary to set a fixed height for the container or component so that the content can expand correctly.

<template>
  <div style="height: 300px;">
    <TuiSteps direction="vertical" :active="1">
      <TuiStep title="Order Placed" description="2023-12-01 12:00" />
      <TuiStep title="Out of Warehouse" description="2023-12-02 08:00" />
      <TuiStep title="Shipping" description="In transit..." />
      <TuiStep title="Signed" />
    </TuiSteps>
  </div>
</template>

Simple Mode

Set simple to true to enable a concise style. In simple mode, titles and icons are arranged horizontally. This is typically used in scenarios with limited space or where detailed descriptions are not required.

• simple: Enables simple mode.
• simpleWithBG: Whether to display the gray background bar (defaults to true).

<template>
  <TuiSteps :active="1" simple :options="stepsData" />

  <TuiSteps :active="1" simple :simpleWithBG="false" :options="stepsData" />
</template>

Status Management

TuiSteps provides powerful status control logic:

1. Global Status Control:
   • processStatus: The status of the current step in progress (default is process).
   • finishStatus: The status of completed steps (default is finish, usually represented by a success color).
2. Single Step Status Override:
   • Specify status within individual step data to forcibly override the status of that step (e.g., to show Error or Warning).

<template>
  <TuiSteps :active="1" processStatus="error">
    <TuiStep title="Step 1" />
    <TuiStep title="Step 2 (Error)" description="Validation failed" />
    <TuiStep title="Step 3" />
  </TuiSteps>

  <TuiSteps :active="2">
    <TuiStep title="Step 1" />
    <TuiStep title="Step 2" status="warning" description="Partially completed" />
    <TuiStep title="Step 3" />
  </TuiSteps>
</template>

API Reference

TuiSteps Props

Property	Type	Default	Description
active	Number	0	The index of the currently active step (starting from 0).
direction	String	'horizontal'	Display direction. Options: 'horizontal', 'vertical'.
options	Array	[]	Data source array. See TuiStep Props below for object structure.
simple	Boolean	false	Whether to enable simple mode.
simpleWithBG	Boolean	true	Whether to display the background in simple mode.
processStatus	String	'process'	The status of the current step. Options: wait, process, finish, error, success, warning.
finishStatus	String	'finish'	The status of completed steps. Usually set to success or finish.
descriptionLines	Number	2	Maximum number of lines for description text (truncated with ellipsis if exceeded).

TuiStep Props (or Options Object Fields)

Property	Type	Default	Description
title	String	''	Title.
description	String	''	Description text.
icon	String	''	Icon class name.
status	String	''	Forced Status. If set, the status calculated from the active index will be ignored. Options: wait, process, finish, error, success, warning.