JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 13
  • Score
    100M100P100Q84975F
  • License MIT

A customizable stepper component library for React with TailwindCSS.

Package Exports

  • stepper-ui

Readme

Stepper UI

stepper-ui is a React component library that provides a customizable and easy-to-use Stepper, ideal for multi-step forms or workflows. Built with React, TypeScript, and designed to integrate with TailwindCSS.

Installation

npm install stepper-ui
# or using pnpm
pnpm add stepper-ui

Make sure to have react and react-dom installed as peerDependencies.

Basic Usage

import { Stepper } from 'stepper-ui';
import { Button } from '@your-ui/button';
import { ArrowLeftIcon, ArrowRightIcon, TaskAddIcon } from '@your-icons';
import { FormPersonData } from './FormPersonData';
import { FormVehicles } from './FormVehicles';

<Stepper
  steps=[
    { name: 'General Information', component: FormPersonData },
    { name: 'Additional Information', component: FormVehicles }
  ]
  renderButtons={({ nextStep, backStep, step, totalSteps }) => (
    <div className="flex justify-between">
      <Button
        color="primary"
        radius="full"
        startContent={<ArrowLeftIcon />}
        onPress={backStep}
        disabled={step === 0}
      >
        Previous
      </Button>
      <Button
        color="primary"
        radius="full"
        className="cursor-pointer"
        endContent={step + 1 === totalSteps ? <TaskAddIcon /> : <ArrowRightIcon />}
        onPress={nextStep}
        disabled={step === totalSteps - 1}
      >
        {step + 1 === totalSteps ? 'Save' : 'Next'}
      </Button>
    </div>
  )}
/>

Props

StepperProps

Prop Type Description Optional
steps StepComponentProps[] Array of steps for the Stepper. Each step has a name and a React component. No
renderButtons (props: RenderButtonsProps) => ReactNode | ReactNode[] Function that receives nextStep and backStep methods and renders the navigation buttons. No
wrapperClassName string Additional TailwindCSS classes for the Stepper container. Yes
renderStepIcon (label:string, step: number, active: boolean, completed: boolean) => ReactNode Function to render a custom icon for each step. Yes

StepComponentProps

Prop Type Description Optional
name string Name of the step displayed in the Stepper. No
component ForwardRefExoticComponent<StepperContextProps & RefAttributes<ValidateStep>>; React component for the step. Must implement ValidateStep if validation is needed. No
icon ReactNode Optional icon displayed next to the step name. Yes

RenderButtonsProps

Prop Type Description
step number Current step (0-based).
nextStep () => void Function to go to the next step.
backStep () => void Function to go back to the previous step.
totalSteps number Total number of steps in the Stepper.

ValidateStep

Method Return Description
canContinue boolean | Promise<boolean> Indicates if the current step allows moving to the next step. Useful for asynchronous validation.

StepperContextProps

Prop Type Description
step number Current step (0-based).
nextStep () => void Function to go to the next step.
backStep () => void Function to go back to the previous step.
navigateTo () => void Function to navigate directly to any step by its index (0-based).
goToInitialStep () => void Function to go back to the first step (step 0).

Example of a Step Component with forwardRef and ValidateStep

import { forwardRef, useImperativeHandle } from "react";
import type { StepperContextProps, ValidateStep } from "stepper-ui";

export const FormPersonData = forwardRef<ValidateStep, StepperContextProps>(
  (props, ref) => {
    // Expose methods to Stepper using ref
    useImperativeHandle(ref, () => ({
      canContinue: () => {
        // Validation logic
        return true; // or Promise<boolean> for async validation
      },
    }));

    return (
      <div>
        {/* Form content */}
        <label>Name:</label>
        <input type="text" />
      </div>
    );
  }
);

Important notes:

  • Each step component must use forwardRef<ValidateStep> if you want Stepper to control navigation based on validation.
  • The canContinue method can return a boolean or a Promise<boolean>.
  • You can expose other methods if needed, but Stepper will only use canContinue.

Recommendations

  • Your project should have TailwindCSS configured if you want to use the included classes.
  • You can use renderStepIcon to add custom icons to each step.
  • Stepper is fully internally controlled; you just need to provide the steps and navigation buttons.

License

MIT © DuarteBv