React-hook-stepper NPM

React Hook Stepper

Introduction

This library provides a powerful hook called useStepper to facilitate managing step flows in React applications. This hook offers properties and functions to create, navigate, and manipulate step states in a flexible and scalable way.

Installation

Install the library using npm:

npm i react-hook-stepper

Install the library using pnpm or yarn:

pnpm i react-hook-stepper

yarn add react-hook-stepper

Hook Returns

`stepperState`

An object containing the complete state of the steps.

`generalInfo`

Provides general information about the process, such as:

totalSteps
currentProgress
completedProgress
canAccessProgress

`steps`

A list of configurations for all steps, including:

name: Name of the step
canAccess: Defines if the step can be accessed
canEdit: Defines if the step can be edited
isOptional: Indicates if the step is optional
isCompleted: Indicates if the step is completed

By default, the boolean values (canAccess, canEdit, isOptional, isCompleted) are set to false if not specified.

Usage Example

export const Step = ({ steps }: { steps: StepConfig[] }) => {
 const { stepperState } = useStepper({ steps });

 return (
  // Implement your component using stepperState
 );
};

`generalstate`

The generalState is a user-provided state that can be used to share information between steps. It can be typed using generics. Example:

interface Step1Type {
 step1: {
  test: string;
  test1: number;
 };
}

export const Step1 = () => {
 const { onNext, onPrev, activeStep } = useStepper<Step1Type>();

 const handleNext = () =>
  onNext({
   updateStepsStatus: [{ stepIndex: 1, data: { canEdit: true } }],
    onCompleteStep: (data) => console.log("Step 1 completed with data:", data),
  });

 return (
  <div>
   <h1>Step 1</h1>
   <button onClick={() => onPrev()}>Previous</button>
   <button onClick={handleNext}>Next</button>
  </div>
 );
};

Recommended Typing

Use extends to reuse the state of previous steps:

interface Step1Type {
 step1: { /* Step 1 values */ };
}

interface Step2Type extends Step1Type {
 step2: { /* Step 2 values */ };
}

interface Step3Type extends Step2Type {
 step3: { /* Step 3 values */ };
}

Alternatively, you can create separate typings for each step if preferred.

`errors`

A place where step errors are stored.
Users can also manually add errors.

This feature is under development.

`activeStep`

Provides the settings of the currently active step:

name
canAccess
canEdit
isOptional
isCompleted
index
isLastStep
isFirstStep

`loading`

Indicates if any asynchronous function (goToStep, onNext, onPrev) is being executed.

Functions

`updateGeneralState`

Updates the generalState

Example:

const updatedState = updateGeneralState({ data: { step1: { /* new values */ } } });
console.log(updatedState);

`updateSteps`

Updates configurations for one or more steps.

Example:

const updatedSteps = updateSteps([{ stepIndex: 2, data: { canEdit: true } }]);
console.log(updatedSteps);

`onNext`

Moves to the next step.

Defaults: Marks the current step as canAccess and isCompleted.

Allows updates to generalState and steps via updateGeneralStates and updateStepsStatus.

Example:

onNext({
 updateGeneralStates: { data: { step1: { /* new values */ } } },
 updateStepsStatus: [{ stepIndex: 2, data: { canEdit: true } }],
 onCompleteStep: async (data) => {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  console.log("Steps data:", data);
 },
});

`onPrev`

Moves back to the previous step. Works similarly to onNext.

Example:

onPrev({
 updateGeneralStates: { data: { step1: { /* new values */ } } },
 updateStepsStatus: [{ stepIndex: 2, data: { canEdit: true } }],
 onCompleteStep: async (data) => {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  console.log("Steps data:", data);
 },
});

`goToStep`

Navigates to a specific step by index. Works similarly to onNext, with the addition of the target step index.

Example:

goToStep(2, {
 updateGeneralStates: { data: { step1: { /* new values */ } } },
 updateStepsStatus: [{ stepIndex: 2, data: { canEdit: true } }],
 onCompleteStep: async (data) => {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  console.log("Step 2 completed with data:", data);
 },
});

You can configure which properties to set as true or false for each function using the initial configuration when creating your component.

Example:

export const Step = ({ steps }: { steps: StepConfig[] }) => {
 const { stepperState } = useStepper({ steps, config: {
  validations: {
   goToStep: {
    canAccess: // true or false
   },
   next: {
    currentStep: {
     canAccess: // true or false
     canEdit: // true or false
     isOptional: // true or false
     isCompleted: // true or false
    },
    nextStep: {
     canAccess: // true or false
     canEdit: // true or false
     isOptional: // true or false
     isCompleted: // true or false
    }
   },
   prev: {
    currentStep: {
     canAccess: // true or false
     canEdit: // true or false
     isOptional: // true or false
     isCompleted: // true or false
    },
    prevStep: {
     canAccess: // true or false
     canEdit: // true or false
     isOptional: // true or false
     isCompleted: // true or false
    }
   },
   goToStep: {
    currentStep: {
     canAccess: // true or false
     canEdit: // true or false
     isOptional: // true or false
     isCompleted: // true or false
    },
    nextStep: {
     canAccess: // true or false
     canEdit: // true or false
     isOptional: // true or false
     isCompleted: // true or false
    }
   },
  }
 }
});

 return (
  // Implement your component using stepperState
 );
};

validations.goToStep.canAccess: Determines whether navigation to a specific step (goToStep(index)) is allowed based on the current step's state.

If true, it validates that the target step's canAccess property is true before allowing navigation. By default, this validation is always performed.

next.currentStep: Sets the properties of the current step when moving to the next step. next.nextStep: Sets the properties of the next step when advancing to it.

prev.currentStep: Sets the properties of the current step when going back to the previous step. prev.prevStep: Sets the properties of the previous step when navigating back to it.

goToStep.currentStep: Sets the properties of the current step when using goToStep(index) to navigate to a specific step.

goToStep.nextStep: Sets the properties of the target step when navigating to it with goToStep(index).

The following properties can be configured for each step:

canAccess Controls whether the step can be accessed.
canEdit Controls whether the step can be edited.
isOptional Indicates if the step is optional.
isCompleted Marks whether the step is completed.

Example:

By default, the entire process is saved in localStorage. However, if you prefer this not to happen, you can configure it using the saveLocalStorage property.

Example:

export const Step = ({ steps }: { steps: StepConfig[] }) => {
 const { stepperState } = useStepper({ steps, config: {
  config: {
   saveLocalStorage: false
  }
 }
});

 return (
  // Implement your component using stepperState
 );
};

The localStorage is automatically cleared when onNext is called during the final step. However, if you want to clear it manually, you can use the cleanLocalStorage method provided by useStepper.

cleanLocalStorage only removes the step-related information.

export const Step1 = () => {
 const { onNext, onPrev, activeStep, cleanLocalStorage } = useStepper();

 const handleCleanLocalStorage = () => {
  cleanLocalStorage();
 }

 const handleNext = () =>
  onNext({
   updateStepsStatus: [{ stepIndex: 1, data: { canEdit: true } }],
    onCompleteStep: (data) => console.log("Step 1 completed with data:", data),
  });

 return (
  <div>
   <h1>Step 1</h1>
   <button onClick={() => onPrev()}>Previous</button>
   <button onClick={handleNext}>Next</button>
   <button onClick={handleCleanLocalStorage}>Clean localStorage</button>
  </div>
 );
};

StepsWithProvider

Example of using the component, after being created on a page:

import { StepsWithProvider, useStepper, StepConfig, ValidationConfigStepper } from "react-hook-stepper";

export const CustomSteper = ({
 steps,
 title,
}: {
 steps: StepConfig[];
 title?: string;
 config: ValidationConfigStepper;
}) => {
 const { stepperState, activeStep, goToStep } = useStepper({ steps, ...config }); // Use the custom hook to manage steps, just pass the steps in main component

 return (
  <div>
   <h1>{title}</h1>
   <div>
    {stepperState.steps.map((step, index) => (
     <div key={index}>
      <div style={{ display: "flex", alignItems: "center", gap: "10px" }}>
        <div onClick={() => goToStep(index)}>
          {activeStep.index > index ? "✔" : index + 1}
        </div>
        <div>{step.name}</div>
      </div>
      {activeStep.index === index && (
        <div> {steps[activeStep.index].component}</div>
      )}
     </div>
    ))}
   </div>
  </div>
 );
};

const HomePage = () => {
 return (
  <div>
   <CustomSteper
    config={{
     // your config
    }}
    steps={[
     { name: "Step 1", component: <Step1 /> },
     { name: "Step 2", component: <Step2 /> },
     { name: "Step 3", component: <Step3 /> },
     { name: "Step 4", component: <Step4 />, isOptional: true },
    ]}
   />
  </div>
 );
};

export default StepsWithProvider(HomePage); // remember to use `StepsWithProvider` to provide the context for the entire flow

steps stepper react multi-step hooks react-hooks

6 months ago

7 months ago

7 months ago

7 months ago

7 months ago

7 months ago