useStep

Custom React hook that manages and navigates between steps in a multi-step process. Perfect for wizards, onboarding flows, and step-by-step forms with Next.js integration and TypeScript support.

Loading component...

"use client";import { useStep } from '@/components/ui/shadcn-io/use-step';export default function UseStepDemo() {  const [currentStep, {    canGoToPrevStep,    canGoToNextStep,    goToNextStep,    goToPrevStep,    reset,    setStep,  }] = useStep(5);  return (    <div className="flex flex-col items-center justify-center min-h-[300px] p-8 space-y-6">      {/* Current Step Display */}      <div className="text-center space-y-2">        <h3 className="text-lg font-semibold">Current Step</h3>        <div className="text-4xl font-bold text-blue-600 dark:text-blue-400">          {currentStep}        </div>        <div className="text-sm text-muted-foreground">Step {currentStep} of 5</div>      </div>      {/* Progress Bar */}      <div className="w-full max-w-xs">        <div className="flex space-x-1">          {Array.from({ length: 5 }, (_, i) => i + 1).map((step) => (            <div              key={step}              className={`flex-1 h-2 rounded-full ${                step <= currentStep                   ? "bg-blue-600"                   : "bg-gray-200 dark:bg-gray-700"              }`}            />          ))}        </div>      </div>      {/* Navigation Controls */}      <div className="flex gap-2 justify-center">        <button          onClick={goToPrevStep}          className="px-3 py-1.5 text-sm bg-gray-600 text-white rounded-md hover:bg-gray-700 transition-colors disabled:opacity-50"          disabled={!canGoToPrevStep}        >          Previous        </button>                <button          onClick={goToNextStep}          className="px-3 py-1.5 text-sm bg-blue-600 text-white rounded-md hover:bg-blue-700 transition-colors disabled:opacity-50"          disabled={!canGoToNextStep}        >          Next        </button>                <button          onClick={reset}          className="px-3 py-1.5 text-sm bg-red-600 text-white rounded-md hover:bg-red-700 transition-colors"        >          Reset        </button>                <button          onClick={() => setStep(3)}          className="px-3 py-1.5 text-sm bg-green-600 text-white rounded-md hover:bg-green-700 transition-colors"        >          Set to step 3        </button>      </div>      {/* Status Information */}      <div className="text-center text-sm text-muted-foreground space-y-1">        <div>Can go to previous step: <code className="bg-muted px-1 py-0.5 rounded">{canGoToPrevStep ? 'yes' : 'no'}</code></div>        <div>Can go to next step: <code className="bg-muted px-1 py-0.5 rounded">{canGoToNextStep ? 'yes' : 'no'}</code></div>      </div>    </div>  );}

Installation

npx shadcn@latest add https://www.shadcn.io/registry/use-step.json

npx shadcn@latest add https://www.shadcn.io/registry/use-step.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-step.json

bunx shadcn@latest add https://www.shadcn.io/registry/use-step.json

Features

Step navigation with automatic boundary checking and validation
Convenient helpers including goToNextStep, goToPrevStep, and reset methods
Boundary validation preventing invalid step transitions with boolean flags
Type safety with comprehensive TypeScript definitions and error handling
Flexible step setting supporting both direct values and function updates
Memory efficient with proper callback memoization to prevent unnecessary re-renders

Examples

Advanced Step Controls

Loading component...

"use client";import { useState } from 'react';import { useStep } from '@/components/ui/shadcn-io/use-step';import { CheckIcon, ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';const stepTitles = [  "Personal Information",  "Contact Details",   "Preferences",  "Review & Confirm"];const stepDescriptions = [  "Enter your basic personal information",  "Provide your contact information",  "Set your account preferences",  "Review and confirm your information"];export default function UseStepAdvancedDemo() {  const [currentStep, {    canGoToPrevStep,    canGoToNextStep,    goToNextStep,    goToPrevStep,    reset,    setStep,  }] = useStep(4);  const [formData, setFormData] = useState({    firstName: '',    lastName: '',    email: '',    phone: '',    notifications: true,    newsletter: false  });  const [completedSteps, setCompletedSteps] = useState<number[]>([]);  const updateFormData = (field: keyof typeof formData, value: string | boolean) => {    setFormData(prev => ({ ...prev, [field]: value }));  };  const validateStep = (step: number): boolean => {    switch (step) {      case 1:        return formData.firstName.trim() !== '' && formData.lastName.trim() !== '';      case 2:        return formData.email.trim() !== '' && formData.phone.trim() !== '';      case 3:        return true; // Preferences are optional      case 4:        return true; // Review step is always valid      default:        return false;    }  };  const handleNext = () => {    if (validateStep(currentStep)) {      if (!completedSteps.includes(currentStep)) {        setCompletedSteps(prev => [...prev, currentStep]);      }      goToNextStep();    }  };  const handleStepClick = (step: number) => {    // Only allow navigation to completed steps or the next step    if (completedSteps.includes(step) || step <= Math.max(...completedSteps, 0) + 1) {      setStep(step);    }  };  const handleReset = () => {    reset();    setCompletedSteps([]);    setFormData({      firstName: '',      lastName: '',      email: '',      phone: '',      notifications: true,      newsletter: false    });  };  const renderStepContent = () => {    switch (currentStep) {      case 1:        return (          <div className="space-y-4">            <h3 className="text-lg font-medium">Personal Information</h3>            <div className="grid grid-cols-1 md:grid-cols-2 gap-4">              <div>                <label className="block text-sm font-medium mb-1">First Name *</label>                <input                  type="text"                  value={formData.firstName}                  onChange={(e) => updateFormData('firstName', e.target.value)}                  className="w-full px-3 py-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 dark:bg-gray-800 dark:border-gray-600"                  placeholder="Enter first name"                />              </div>              <div>                <label className="block text-sm font-medium mb-1">Last Name *</label>                <input                  type="text"                  value={formData.lastName}                  onChange={(e) => updateFormData('lastName', e.target.value)}                  className="w-full px-3 py-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 dark:bg-gray-800 dark:border-gray-600"                  placeholder="Enter last name"                />              </div>            </div>          </div>        );      case 2:        return (          <div className="space-y-4">            <h3 className="text-lg font-medium">Contact Details</h3>            <div className="space-y-4">              <div>                <label className="block text-sm font-medium mb-1">Email *</label>                <input                  type="email"                  value={formData.email}                  onChange={(e) => updateFormData('email', e.target.value)}                  className="w-full px-3 py-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 dark:bg-gray-800 dark:border-gray-600"                  placeholder="Enter email address"                />              </div>              <div>                <label className="block text-sm font-medium mb-1">Phone Number *</label>                <input                  type="tel"                  value={formData.phone}                  onChange={(e) => updateFormData('phone', e.target.value)}                  className="w-full px-3 py-2 border rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 dark:bg-gray-800 dark:border-gray-600"                  placeholder="Enter phone number"                />              </div>            </div>          </div>        );      case 3:        return (          <div className="space-y-4">            <h3 className="text-lg font-medium">Preferences</h3>            <div className="space-y-3">              <div className="flex items-center space-x-2">                <input                  type="checkbox"                  id="notifications"                  checked={formData.notifications}                  onChange={(e) => updateFormData('notifications', e.target.checked)}                  className="rounded"                />                <label htmlFor="notifications" className="text-sm">Enable notifications</label>              </div>              <div className="flex items-center space-x-2">                <input                  type="checkbox"                  id="newsletter"                  checked={formData.newsletter}                  onChange={(e) => updateFormData('newsletter', e.target.checked)}                  className="rounded"                />                <label htmlFor="newsletter" className="text-sm">Subscribe to newsletter</label>              </div>            </div>          </div>        );      case 4:        return (          <div className="space-y-4">            <h3 className="text-lg font-medium">Review & Confirm</h3>            <div className="bg-gray-50 dark:bg-gray-800 p-4 rounded-md space-y-2">              <div><strong>Name:</strong> {formData.firstName} {formData.lastName}</div>              <div><strong>Email:</strong> {formData.email}</div>              <div><strong>Phone:</strong> {formData.phone}</div>              <div><strong>Notifications:</strong> {formData.notifications ? 'Enabled' : 'Disabled'}</div>              <div><strong>Newsletter:</strong> {formData.newsletter ? 'Subscribed' : 'Not subscribed'}</div>            </div>            <div className="text-center">              <button className="px-6 py-3 bg-green-600 text-white rounded-md hover:bg-green-700 transition-colors">                Complete Registration              </button>            </div>          </div>        );      default:        return null;    }  };  return (    <div className="max-w-lg mx-auto p-6 space-y-6">      {/* Step Indicator */}      <div className="flex items-center justify-between">        {stepTitles.map((title, index) => {          const stepNum = index + 1;          const isActive = stepNum === currentStep;          const isCompleted = completedSteps.includes(stepNum);          const isClickable = completedSteps.includes(stepNum) || stepNum <= Math.max(...completedSteps, 0) + 1;                    return (            <div key={stepNum} className="flex items-center">              <button                onClick={() => handleStepClick(stepNum)}                disabled={!isClickable}                className={`w-10 h-10 rounded-full flex items-center justify-center text-sm font-medium transition-colors ${                  isActive                    ? "bg-blue-600 text-white"                    : isCompleted                    ? "bg-green-600 text-white"                    : isClickable                    ? "bg-gray-200 text-gray-800 hover:bg-gray-300 dark:bg-gray-700 dark:text-gray-200"                    : "bg-gray-100 text-gray-400 dark:bg-gray-800 dark:text-gray-600 cursor-not-allowed"                }`}              >                {isCompleted ? <CheckIcon className="w-5 h-5" /> : stepNum}              </button>              {index < stepTitles.length - 1 && (                <div className={`w-12 h-0.5 mx-2 ${                  completedSteps.includes(stepNum) ? "bg-green-600" : "bg-gray-200 dark:bg-gray-700"                }`} />              )}            </div>          );        })}      </div>      {/* Step Title and Description */}      <div className="text-center space-y-2">        <h2 className="text-xl font-semibold">{stepTitles[currentStep - 1]}</h2>        <p className="text-muted-foreground">{stepDescriptions[currentStep - 1]}</p>      </div>      {/* Step Content */}      <div className="min-h-[200px]">        {renderStepContent()}      </div>      {/* Navigation */}      <div className="flex justify-between items-center">        <button          onClick={goToPrevStep}          disabled={!canGoToPrevStep}          className="flex items-center space-x-2 px-4 py-2 border rounded-md hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"        >          <ChevronLeftIcon className="w-4 h-4" />          <span>Previous</span>        </button>        <div className="flex space-x-2">          <button            onClick={handleReset}            className="px-4 py-2 text-gray-600 dark:text-gray-400 hover:text-gray-800 dark:hover:text-gray-200 transition-colors"          >            Start Over          </button>                    {canGoToNextStep ? (            <button              onClick={handleNext}              disabled={!validateStep(currentStep)}              className="flex items-center space-x-2 px-6 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition-colors disabled:opacity-50 disabled:cursor-not-allowed"            >              <span>Next</span>              <ChevronRightIcon className="w-4 h-4" />            </button>          ) : (            <div className="text-center">              <div className="text-green-600 font-medium">All steps completed!</div>            </div>          )}        </div>      </div>      {/* Validation Status */}      {!validateStep(currentStep) && (        <div className="text-center text-sm text-red-600">          Please fill in all required fields to continue        </div>      )}    </div>  );}

Demonstrates a complete multi-step workflow with progress indicators, conditional navigation, and step validation.

Use Cases

This free open source React hook works well for:

Onboarding flows - Guide users through multi-step registration or setup processes
Wizards and forms - Step-by-step data collection with Next.js and TypeScript
Checkout processes - Navigate through cart, shipping, payment, and confirmation steps
Tutorial systems - Interactive tutorials and guided tours built with React
Progress workflows - Track user progress through complex multi-stage processes
Installation guides - Step-by-step software or configuration setup flows

API Reference

Parameter	Type	Description
`maxStep`	`number`	The maximum step in the process (must be >= 1)

Return Array

Returns a tuple: [currentStep, actions]

Index	Type	Description
`0`	`number`	Current step number (1-based indexing)
`1`	`UseStepActions`	Object containing navigation methods and state flags

UseStepActions Object

Property	Type	Description
`canGoToNextStep`	`boolean`	Whether navigation to next step is possible
`canGoToPrevStep`	`boolean`	Whether navigation to previous step is possible
`goToNextStep`	`() => void`	Memoized function to go to the next step
`goToPrevStep`	`() => void`	Memoized function to go to the previous step
`reset`	`() => void`	Memoized function to reset to step 1
`setStep`	`Dispatch<SetStateAction<number>>`	Direct step setter with validation

Usage Patterns

Basic Usage

const [
  currentStep,
  { goToNextStep, goToPrevStep, canGoToNextStep, canGoToPrevStep },
] = useStep(5);

// Navigate forward
if (canGoToNextStep) {
  goToNextStep();
}

// Navigate backward
if (canGoToPrevStep) {
  goToPrevStep();
}

With Step Setting

const [currentStep, { setStep, reset }] = useStep(10);

// Jump to specific step
setStep(5);

// Using function syntax
setStep((prev) => prev + 2);

// Reset to beginning
reset();

Wizard Implementation

const [currentStep, helpers] = useStep(4);
const { goToNextStep, goToPrevStep, canGoToNextStep, canGoToPrevStep, reset } =
  helpers;

const handleNext = () => {
  if (validateCurrentStep()) {
    goToNextStep();
  }
};

return (
  <div>
    <WizardStep step={currentStep} />
    <button onClick={goToPrevStep} disabled={!canGoToPrevStep}>
      Previous
    </button>
    <button onClick={handleNext} disabled={!canGoToNextStep}>
      Next
    </button>
    <button onClick={reset}>Start Over</button>
  </div>
);

Implementation Notes

Hook starts at step 1 and validates that maxStep is a positive number
All navigation functions respect boundaries and will not exceed maxStep or go below 1
Step validation throws descriptive errors for invalid step values in setStep
All helper functions are memoized with useCallback for optimal performance
Compatible with React 16.8+ and follows hooks rules and conventions
Works seamlessly with TypeScript for full type safety and IntelliSense
Helper methods have stable references across re-renders for performance
Step setting supports both direct values and functional updates like useState

useStep

On this page