Implementing 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.

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

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

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

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

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

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

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

Advanced Styling & Customization

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

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

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

Best Practices: Accessibility & Localization

📄 Read: references/accessibility-globalization.md

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

Quick Start Examples

Pattern 1: Component-Based (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;

Pattern 2: Property-Based (steps Array)

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

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

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

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

Step Properties (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)

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

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

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

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

syncfusion-react-stepper

NPX Install

Tags

SKILL.md Content