syncfusion-react-stepper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React Stepper

实现Syncfusion React Stepper

The Stepper component guides users through a multi-step workflow or process with visual indicators, step labels, and flexible configuration. It's ideal for wizards, checkout flows, onboarding processes, and any guided user experience requiring sequential navigation.

Stepper组件通过视觉指示器、步骤标签和灵活的配置引导用户完成多步骤工作流或流程，非常适合用于向导、结账流程、新手引导流程以及任何需要顺序导航的引导式用户体验。

When to Use This Skill

何时使用本技能

Use the Stepper component when you need to:

Guide users through multi-step processes (checkout, registration, setup wizards)
Display step-by-step workflows with progress indication
Validate user input before advancing to the next step
Support linear or non-linear navigation patterns
Customize appearance with icons, labels, and templates
Localize content for different languages/regions

当你需要实现以下需求时可使用Stepper组件：

引导用户完成多步骤流程（结账、注册、设置向导）
展示带进度提示的分步工作流
进入下一步前校验用户输入
支持线性或非线性导航模式
用图标、标签和模板自定义外观
针对不同语言/地区做内容本地化

Component Overview

组件概览

Key Capabilities:

Step Navigation: Horizontal and vertical orientations, sequential or free navigation
Step Types: Default (icons + labels), label-only, or indicator-only modes
Events: Track step changes, validations, and interactions
Styling: Animations, templates, custom CSS, and tooltips
Accessibility: Full keyboard navigation and ARIA support
Globalization: Multi-language support and RTL compatibility

核心能力：

步骤导航： 水平和垂直方向、顺序或自由导航
步骤类型： 默认（图标+标签）、仅标签、仅指示器模式
事件： 追踪步骤变更、校验和交互行为
样式： 动画、模板、自定义CSS和提示框
可访问性： 完整的键盘导航和ARIA支持
全球化： 多语言支持和RTL适配

Documentation and Navigation Guide

文档和导航指南

Getting Started & Installation

入门与安装

📄 Read: references/getting-started.md

Package installation and dependencies
CSS imports and theme setup
Creating your first stepper
Initial configuration and rendering

📄 阅读： references/getting-started.md

包安装和依赖管理
CSS导入和主题设置
创建你的第一个stepper
初始配置和渲染

Core Configuration: Steps and Properties

核心配置：步骤和属性

📄 Read: references/steps-and-configuration.md

Adding and defining steps with StepDirective
Icon CSS, text, and label properties
Active step management
Disabled states and customization
CSS class configuration

📄 阅读： references/steps-and-configuration.md

用StepDirective添加和定义步骤
图标CSS、文本和标签属性
激活步骤管理
禁用状态和自定义
CSS类配置

Layout & Appearance: Orientations and Types

布局与外观：方向和类型

📄 Read: references/orientations-and-types.md

Horizontal and vertical orientations
Step type modes (Default, Label, Indicator)
Label positioning (Top, Bottom, Start, End)
RTL support and responsive design

📄 阅读： references/orientations-and-types.md

水平和垂直方向
步骤类型模式（默认、标签、指示器）
标签位置（上、下、左、右）
RTL支持和响应式设计

Interaction & Behavior: Events

交互与行为：事件

📄 Read: references/events-and-interactions.md

Lifecycle events: created, stepChanged, stepChanging
User interaction events: stepClick, beforeStepRender
Event arguments and handling patterns
Preventing unwanted transitions

📄 阅读： references/events-and-interactions.md

生命周期事件：created、stepChanged、stepChanging
用户交互事件：stepClick、beforeStepRender
事件参数和处理模式
阻止不必要的步骤切换

Workflow Control: Linear Flow and Validation

工作流控制：线性流和校验

📄 Read: references/linear-flow-and-validation.md

Linear stepper configuration for sequential navigation
Step validation and status management
Preventing invalid transitions
Resetting stepper state

📄 阅读： references/linear-flow-and-validation.md

用于顺序导航的线性stepper配置
步骤校验和状态管理
阻止无效切换
重置stepper状态

Advanced Styling & Customization

高级样式与自定义

📄 Read: references/animation-template-tooltip.md

Animation configuration and timing
Template customization for steps
Tooltip integration and display
Custom content rendering

📄 阅读： references/animation-template-tooltip.md

动画配置和时长设置
步骤模板自定义
提示框集成和展示
自定义内容渲染

Methods and Advanced Patterns

方法和高级模式

📄 Read: references/methods-and-advanced.md

Component methods (reset, etc.)
Both API patterns (component-based vs property-based)
Advanced use cases and patterns
Performance optimization tips

📄 阅读： references/methods-and-advanced.md

组件方法（reset等）
两种API模式（基于组件/基于属性）
高级用例和模式
性能优化技巧

Best Practices: Accessibility & Localization

最佳实践：可访问性与本地化

📄 Read: references/accessibility-globalization.md

WCAG compliance and ARIA attributes
Keyboard navigation guidelines
Globalization and localization
RTL support implementation

📄 阅读： references/accessibility-globalization.md

WCAG合规和ARIA属性
键盘导航指南
全球化和本地化
RTL支持实现

Quick Start Examples

快速入门示例

Pattern 1: Component-Based (StepsDirective)

模式1：基于组件（StepsDirective）

jsx

import React from 'react';
import { StepperComponent, StepsDirective, StepDirective } from '@syncfusion/ej2-react-navigations';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-navigations/styles/tailwind3.css';

function App() {
  return (
    <div>
      <StepperComponent>
        <StepsDirective>
          <StepDirective iconCss="sf-icon-cart" label="Cart" />
          <StepDirective iconCss="sf-icon-transport" label="Delivery" />
          <StepDirective iconCss="sf-icon-payment" label="Payment" />
          <StepDirective iconCss="sf-icon-success" label="Confirmation" />
        </StepsDirective>
      </StepperComponent>
    </div>
  );
}

export default App;

jsx

import React from 'react';
import { StepperComponent, StepsDirective, StepDirective } from '@syncfusion/ej2-react-navigations';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-navigations/styles/tailwind3.css';

function App() {
  return (
    <div>
      <StepperComponent>
        <StepsDirective>
          <StepDirective iconCss="sf-icon-cart" label="Cart" />
          <StepDirective iconCss="sf-icon-transport" label="Delivery" />
          <StepDirective iconCss="sf-icon-payment" label="Payment" />
          <StepDirective iconCss="sf-icon-success" label="Confirmation" />
        </StepsDirective>
      </StepperComponent>
    </div>
  );
}

export default App;

Pattern 2: Property-Based (steps Array)

模式2：基于属性（steps数组）

jsx

import React from 'react';
import { StepperComponent } from '@syncfusion/ej2-react-navigations';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-navigations/styles/tailwind3.css';

function App() {
  const steps = [
    { iconCss: 'sf-icon-cart', label: 'Cart' },
    { iconCss: 'sf-icon-transport', label: 'Delivery' },
    { iconCss: 'sf-icon-payment', label: 'Payment' },
    { iconCss: 'sf-icon-success', label: 'Confirmation' }
  ];

  return (
    <div>
      <StepperComponent steps={steps} />
    </div>
  );
}

export default App;

jsx

import React from 'react';
import { StepperComponent } from '@syncfusion/ej2-react-navigations';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-navigations/styles/tailwind3.css';

function App() {
  const steps = [
    { iconCss: 'sf-icon-cart', label: 'Cart' },
    { iconCss: 'sf-icon-transport', label: 'Delivery' },
    { iconCss: 'sf-icon-payment', label: 'Payment' },
    { iconCss: 'sf-icon-success', label: 'Confirmation' }
  ];

  return (
    <div>
      <StepperComponent steps={steps} />
    </div>
  );
}

export default App;

Common Patterns

常用模式

Pattern 1: Wizard with Validation

模式1：带校验的向导

jsx

const [activeStep, setActiveStep] = React.useState(0);
const stepperRef = React.useRef(null);

const handleStepChanging = (args) => {
  // Validate current step before advancing
  if (!validateStep(activeStep)) {
    args.cancel = true; // Prevent transition
  }
};

<StepperComponent 
  ref={stepperRef}
  stepChanging={handleStepChanging}
>
  {/* steps */}
</StepperComponent>

jsx

const [activeStep, setActiveStep] = React.useState(0);
const stepperRef = React.useRef(null);

const handleStepChanging = (args) => {
  // Validate current step before advancing
  if (!validateStep(activeStep)) {
    args.cancel = true; // Prevent transition
  }
};

<StepperComponent 
  ref={stepperRef}
  stepChanging={handleStepChanging}
>
  {/* steps */}
</StepperComponent>

Pattern 2: Linear vs Non-Linear Navigation

模式2：线性vs非线性导航

jsx

// Linear: Users must complete steps sequentially
<StepperComponent linear={true}>

// Non-linear: Users can skip to any step
<StepperComponent linear={false}>

jsx

// Linear: Users must complete steps sequentially
<StepperComponent linear={true}>

// Non-linear: Users can skip to any step
<StepperComponent linear={false}>

Pattern 3: Responsive Orientation

模式3：响应式方向

jsx

// Auto-switch orientation based on screen size
const [orientation, setOrientation] = React.useState('horizontal');

React.useEffect(() => {
  const handleResize = () => {
    setOrientation(window.innerWidth < 768 ? 'vertical' : 'horizontal');
  };
  window.addEventListener('resize', handleResize);
  return () => window.removeEventListener('resize', handleResize);
}, []);

<StepperComponent orientation={orientation}>

jsx

// Auto-switch orientation based on screen size
const [orientation, setOrientation] = React.useState('horizontal');

React.useEffect(() => {
  const handleResize = () => {
    setOrientation(window.innerWidth < 768 ? 'vertical' : 'horizontal');
  };
  window.addEventListener('resize', handleResize);
  return () => window.removeEventListener('resize', handleResize);
}, []);

<StepperComponent orientation={orientation}>

Key Props and Configuration

核心属性和配置

Component Properties

组件属性

Prop	Type	Default	Purpose
`activeStep`	number	0	Currently active step index
`animation`	StepperAnimationSettingsModel	undefined	Animation configuration (enable, duration, delay)
`cssClass`	string	''	CSS class for custom styling
`enablePersistence`	boolean	false	Persist component state between page reloads
`enableRtl`	boolean	false	Enable right-to-left layout
`labelPosition`	string	'Bottom'	Label placement: 'Top', 'Bottom', 'Start', 'End'
`linear`	boolean	false	Enforce sequential step navigation
`locale`	string	'en-US'	Localization culture code
`orientation`	string	'horizontal'	Layout direction: 'horizontal' or 'vertical'
`readOnly`	boolean	false	Disable user interaction
`showTooltip`	boolean	true	Show tooltips on hover
`stepType`	string	'Default'	Visual mode: 'Default', 'Label', 'Indicator'
`steps`	StepModel[]	[]	Array of step objects (property-based pattern)
`template`	string \| function	undefined	Custom template for steps
`tooltipTemplate`	string \| function	undefined	Custom template for tooltips

Prop	类型	默认值	用途
`activeStep`	number	0	当前激活步骤的索引
`animation`	StepperAnimationSettingsModel	undefined	动画配置（启用、时长、延迟）
`cssClass`	string	''	用于自定义样式的CSS类
`enablePersistence`	boolean	false	页面重载之间持久化组件状态
`enableRtl`	boolean	false	启用从右到左布局
`labelPosition`	string	'Bottom'	标签位置：'Top'、'Bottom'、'Start'、'End'
`linear`	boolean	false	强制按顺序进行步骤导航
`locale`	string	'en-US'	本地化文化代码
`orientation`	string	'horizontal'	布局方向：'horizontal'或'vertical'
`readOnly`	boolean	false	禁用用户交互
`showTooltip`	boolean	true	hover时展示提示框
`stepType`	string	'Default'	视觉模式：'Default'、'Label'、'Indicator'
`steps`	StepModel[]	[]	步骤对象数组（基于属性的模式）
`template`	string \| function	undefined	步骤的自定义模板
`tooltipTemplate`	string \| function	undefined	提示框的自定义模板

Step Properties (StepModel)

步骤属性（StepModel）

Property	Type	Purpose
`cssClass`	string	CSS class for individual step styling
`disabled`	boolean	Disable the step
`iconCss`	string	Icon CSS class for the step
`isValid`	boolean	Validation status of the step
`label`	string	Step label text
`optional`	boolean	Mark step as optional
`status`	string	Step status: 'NotStarted', 'InProgress', 'Completed'
`text`	string	Text content (usually number)

属性	类型	用途
`cssClass`	string	单个步骤自定义样式的CSS类
`disabled`	boolean	禁用该步骤
`iconCss`	string	步骤的图标CSS类
`isValid`	boolean	步骤的校验状态
`label`	string	步骤标签文本
`optional`	boolean	标记步骤为可选
`status`	string	步骤状态：'NotStarted'、'InProgress'、'Completed'
`text`	string	文本内容（通常为数字）

Animation Settings

动画设置

Property	Type	Default	Purpose
`enable`	boolean	true	Enable animations
`duration`	number	400	Animation duration in milliseconds
`delay`	number	0	Delay before animation starts

属性	类型	默认值	用途
`enable`	boolean	true	启用动画
`duration`	number	400	动画时长（单位：毫秒）
`delay`	number	0	动画开始前的延迟

Events

事件

Event	Fires	Use For	Arguments
`created`	After component initialization	Setup, initialization	Event
`stepChanged`	After step changes	Update UI, load content	StepperChangedEventArgs
`stepChanging`	Before step changes	Validate, prevent transitions	StepperChangingEventArgs
`stepClick`	User clicks step	Track interactions	StepperClickEventArgs
`beforeStepRender`	Before rendering each step	Customize step appearance	StepperRenderingEventArgs

事件	触发时机	用途	参数
`created`	组件初始化完成后	初始化配置	Event
`stepChanged`	步骤变更后	更新UI、加载内容	StepperChangedEventArgs
`stepChanging`	步骤变更前	校验、阻止切换	StepperChangingEventArgs
`stepClick`	用户点击步骤时	追踪交互	StepperClickEventArgs
`beforeStepRender`	每个步骤渲染前	自定义步骤外观	StepperRenderingEventArgs

Methods

方法

Method	Parameters	Returns	Purpose
`reset()`	none	void	Reset stepper to initial state (activeStep: 0)
`nextStep()`	none	void	Move to next step programmatically
`previousStep()`	none	void	Move to previous step programmatically
`refreshProgressbar()`	none	void	Refresh progress bar on container resize
`destroy()`	none	void	Destroy component and release resources

Event Arguments Reference:

StepperChangedEventArgs: activeStep, previousStep, isInteracted, name, event, element
StepperChangingEventArgs: activeStep, previousStep, cancel, isInteracted, name, event, element
StepperClickEventArgs: activeStep, name, event, element
StepperRenderingEventArgs: activeStep, name, element

方法	参数	返回值	用途
`reset()`	无	void	重置stepper到初始状态（activeStep: 0）
`nextStep()`	无	void	编程式跳转到下一个步骤
`previousStep()`	无	void	编程式跳转到上一个步骤
`refreshProgressbar()`	无	void	容器尺寸变化时刷新进度条
`destroy()`	无	void	销毁组件并释放资源

事件参数参考：

StepperChangedEventArgs： activeStep、previousStep、isInteracted、name、event、element
StepperChangingEventArgs： activeStep、previousStep、cancel、isInteracted、name、event、element
StepperClickEventArgs： activeStep、name、event、element
StepperRenderingEventArgs： activeStep、name、element

Common Use Cases

常见用例

E-Commerce Checkout: Multi-step checkout flow with order review, shipping, payment
User Registration: Multi-step signup with email, profile, verification
Setup Wizards: Software onboarding with configuration steps
Survey Forms: Step-by-step questionnaire with progress indication
Installation Guides: Installation steps with instructions and validation

电商结账： 包含订单预览、物流、支付环节的多步骤结账流程
用户注册： 包含邮箱、个人资料、验证环节的多步骤注册
设置向导： 包含配置步骤的软件新手引导
调研表单： 带进度提示的分步问卷
安装指南： 带说明和校验的安装步骤