React useStep Hook

Ever tried to manage step navigation in React and ended up with manual step counting chaos, boundary checking nightmares, or broken wizard state management? You know the drill—manually incrementing step numbers, forgetting to check minimum/maximum boundaries, dealing with step validation logic, handling reset functionality. This free open source React useStep custom hook handles all that step management complexity so you can focus on building smooth workflows instead of debugging navigation edge cases in your React applications.

useStep showcase

Smart step navigation with automatic boundary validation and progress tracking:

"use client";import { toast } from "sonner";import { Button } from "@/components/ui/button";import { Badge } from "@/components/ui/badge";import { Label } from "@/components/ui/label";import { Progress } from "@/components/ui/progress";import { useStep } from '@/components/ui/shadcn-io/use-step';export default function UseStepDemo() {  const [currentStep, {    canGoToPrevStep,    canGoToNextStep,    goToNextStep,    goToPrevStep,    reset,    setStep,  }] = useStep(5);  const handleNext = () => {    goToNextStep();    toast.success("Step advanced! 👍", {      description: `Now on step ${currentStep + 1}`,    });  };  const handlePrevious = () => {    goToPrevStep();    toast.success("Step back! 👈", {      description: `Now on step ${currentStep - 1}`,    });  };  const handleReset = () => {    reset();    toast.success("Steps reset! 🔄", {      description: "Back to step 1",    });  };  const handleJumpToStep = () => {    setStep(3);    toast.success("Jumped to step 3! 🎯", {      description: "Direct step navigation",    });  };  const progressValue = ((currentStep - 1) / 4) * 100;  return (    <div className="p-6 max-w-sm mx-auto space-y-4">      {/* Header */}      <div className="text-center space-y-1">        <h3 className="text-lg font-semibold">Step Navigation Demo</h3>        <p className="text-sm text-muted-foreground">Multi-step process control</p>      </div>            {/* Current Step Display */}      <div className="space-y-2">        <Label className="text-sm font-medium">Current Step</Label>        <div className="bg-muted rounded p-2 min-h-[50px] flex items-center justify-center">          <div className="text-center">            <div className="text-2xl font-bold text-primary mb-1">{currentStep}</div>            <Badge variant="outline" className="text-xs">of 5 steps</Badge>          </div>        </div>      </div>      {/* Progress Bar */}      <div className="space-y-2">        <Label className="text-sm font-medium">Progress</Label>        <div className="space-y-1">          <Progress value={progressValue} className="h-2" />          <div className="text-xs text-muted-foreground text-center">            {progressValue.toFixed(0)}% complete          </div>        </div>      </div>      {/* Navigation Controls */}      <div className="space-y-2">        <Label className="text-sm font-medium">Navigation</Label>        <div className="grid grid-cols-2 gap-2 h-10">          <Button            onClick={handlePrevious}            disabled={!canGoToPrevStep}            variant="outline"            size="sm"            className="h-10 text-xs"          >            Previous          </Button>          <Button            onClick={handleNext}            disabled={!canGoToNextStep}            variant="default"            size="sm"            className="h-10 text-xs"          >            Next          </Button>        </div>      </div>      {/* Action Controls */}      <div className="space-y-2">        <Label className="text-sm font-medium">Actions</Label>        <div className="grid grid-cols-2 gap-2 h-10">          <Button            onClick={handleJumpToStep}            variant="outline"            size="sm"            className="h-10 text-xs"          >            Jump to 3          </Button>          <Button            onClick={handleReset}            variant="destructive"            size="sm"            className="h-10 text-xs"          >            Reset          </Button>        </div>      </div>      {/* Instructions */}      <div className="text-center min-h-[16px] flex items-center justify-center">        <div className="text-xs text-muted-foreground">          Navigate through steps with boundary checking        </div>      </div>    </div>  );}

import * as React from "react"import { Slot } from "@radix-ui/react-slot"import { cva, type VariantProps } from "class-variance-authority"import { cn } from "@/lib/utils"const buttonVariants = cva(  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",  {    variants: {      variant: {        default:          "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",        destructive:          "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",        outline:          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",        secondary:          "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",        ghost:          "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",        link: "text-primary underline-offset-4 hover:underline",      },      size: {        default: "h-9 px-4 py-2 has-[>svg]:px-3",        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",        icon: "size-9",      },    },    defaultVariants: {      variant: "default",      size: "default",    },  })function Button({  className,  variant,  size,  asChild = false,  ...props}: React.ComponentProps<"button"> &  VariantProps<typeof buttonVariants> & {    asChild?: boolean  }) {  const Comp = asChild ? Slot : "button"  return (    <Comp      data-slot="button"      className={cn(buttonVariants({ variant, size, className }))}      {...props}    />  )}export { Button, buttonVariants }

This free open source React hook simplifies multi-step process management with TypeScript support for modern JavaScript applications. Whether you're building onboarding flows, form wizards, or checkout processes in your Next.js projects, this React hook keeps your step navigation reliable and user-friendly.

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

Why most step navigation implementations suck

Look, you could keep manually managing step state with useState and boundary checking. But then you hit the step navigation complexity—off-by-one errors, forgotten boundary validation, inconsistent navigation patterns, performance issues from re-creating functions in React applications.

Most developers manually track step counts with useState without proper boundary checking, leading to navigation bugs when users reach edge cases in TypeScript components. Or they create new callback functions on every render, causing unnecessary re-renders and performance issues. Some forget to handle edge cases like jumping to invalid steps or resetting to the beginning in Next.js projects.

This React hook uses optimized step management under the hood, with automatic boundary checking and memoized navigation functions in JavaScript applications. The browser handles all the state updates, plus you get comprehensive validation and helper methods in one call.

Plus it handles all the edge cases—boundary validation with descriptive errors, memoized callbacks for performance, flexible step setting with functional updates in React development. No more broken step navigation or inconsistent wizard behavior.

This free open source React hook manages step state while you focus on building features. Whether you're creating React applications, Next.js interfaces, or TypeScript components, reliable step navigation keeps your JavaScript development smooth.

Features

• Step navigation with automatic boundary checking and comprehensive validation in React applications
• Convenient helpers including goToNextStep, goToPrevStep, and reset methods in TypeScript components
• Boundary validation preventing invalid step transitions with boolean flags in Next.js projects
• Type safety with comprehensive TypeScript definitions and error handling for JavaScript development
• Flexible step setting supporting both direct values and function updates for React frameworks
• Memory efficient with proper callback memoization to prevent unnecessary re-renders in modern applications
• Free open source designed for modern React development workflows

When you'll actually use this

Real talk—this isn't for simple page navigation in React applications. React Router handles route-based flows perfectly. But when you need stateful step management within a component or complex wizard logic, this React hook delivers in Next.js projects.

Perfect for:

• Onboarding sequences - Guide users through registration, setup, or tutorial flows built with TypeScript
• Form wizards - Break complex forms into digestible, validated steps using React patterns
• Checkout processes - Navigate through cart, shipping, payment, and confirmation in JavaScript applications
• Installation guides - Step-by-step software configuration or setup processes in React components
• Survey flows - Multi-page questionnaires with conditional logic in Next.js applications
• Tutorial systems - Interactive guided tours with progress tracking using TypeScript safety

API Reference

useStep

useStep(maxStep: number): [number, UseStepActions]

Return Value

Returns a tuple: [currentStep, actions]

UseStepActions

Common gotchas

Boundary checking is automatic: The React hook prevents navigation beyond the defined step range (1 to maxStep) in React applications. goToNextStep and goToPrevStep will not execute if they would result in invalid step numbers, and the boolean flags reflect this state.

Step numbering starts at 1: Unlike array indexing, steps use 1-based numbering to match user interface conventions in TypeScript components. This makes it intuitive when displaying "Step 1 of 5" but remember to adjust if using with 0-based arrays.

Functions are memoized for performance: All navigation functions maintain stable references across re-renders using useCallback in Next.js projects. This prevents unnecessary re-renders of child components but means they're safe to include in dependency arrays.

setStep validates boundaries: The direct setter function automatically clamps values to the valid range in JavaScript applications. Setting a step below 1 will result in step 1, and setting above maxStep will result in the maximum step.

Step changes trigger re-renders: Every step navigation will cause component re-renders in React frameworks. Consider memoizing expensive child components that don't need to update on step changes.

Initial step is always 1: The React hook always starts at step 1 and doesn't support custom initial steps in TypeScript projects. Use setStep() in useEffect if you need to start at a different step.

Related hooks you will also like

Questions you might have