react-use-wizard

You can attach asynchronous logic to a step using handleStep. This is useful for performing API calls or validations before proceeding to the next step.

• If the handler is async or returns a Promise, isLoading will become true while the promise is pending.
• If the handler throws an error, the wizard will stay on the current step and rethrow the error, allowing you to handle it with a try-catch block.
• If the handler succeeds, the wizard automatically proceeds to the next step.

const Step1 = () => {
  const { handleStep } = useWizard();

  // Async function
  handleStep(async () => {
    await fetch(...);
  });

  // OR

  // Return promise
  handleStep(() => {
    return fetch(...);
  });

  // ...
}

To create a wizard, wrap your step components in the Wizard component. Inside each step component, use the useWizard hook to access navigation methods like nextStep and previousStep.

Note: You cannot use useWizard in the same component where Wizard is defined; it must be used in a child component of Wizard.

import * as React from 'react';
import { Wizard, useWizard } from 'react-use-wizard';

const App = () => (
  <Wizard>
    <Step1 />
    <Step2 />
    <Step3 />
  </Wizard>
);

const Step1 = () => {
  const { handleStep, previousStep, nextStep } = useWizard();

  // Attach an optional handler
  handleStep(() => {
    alert('Going to step 2');
  });

  return (
    <>
      <button onClick={() => previousStep()}>Previous ⏮️</button>
      <button onClick={() => nextStep()}>Next ⏭</button>
    </>
  );
};

To use react-use-wizard in your project, install it using yarn:

yarn add react-use-wizard

Since react-use-wizard is logic-focused, you can use any animation library (like framer-motion) to animate step transitions. A common pattern is to use the wrapper prop on the Wizard component to wrap the active step in an animation component like <AnimatePresence />.

// Example: Wrap steps in an <AnimatePresence> from framer-motion 
const Wrapper = () => <AnimatePresence exitBeforeEnter />;

const App = () => {
  return (
    <Wizard 
        header={<Header />}
        footer={<Footer />}
        wrapper={<Wrapper />}
      >
      <Step1 />
      <Step2 />
    </Wizard>
  );
};

You can explore live, interactive implementations of react-use-wizard using the provided CodeSandbox links for different frameworks. These examples demonstrate how to integrate the wizard logic into specific environments like Gatsby and Next.js.

| Name   | Link                                                                                |
| ------ | ----------------------------------------------------------------------------------- |
| Gatsby | https://codesandbox.io/s/github/devrnt/react-use-wizard/tree/main/examples/gatsby |
| NextJS | https://codesandbox.io/s/github/devrnt/react-use-wizard/tree/main/examples/nextjs |

The useWizard hook provides methods and properties to manage the wizard state from within step components. Ensure the component calling this hook is a child of a Wizard component.

const { 
  nextStep, 
  previousStep, 
  goToStep, 
  handleStep, 
  isLoading, 
  activeStep, 
  stepCount, 
  isFirstStep, 
  isLastStep 
} = useWizard();

The Wizard component wraps your steps and provides layout structure. Each child component passed to Wizard is treated as an individual step.

<Wizard 
    startIndex={0}
    header={<Header />}
    footer={<Footer />}
    wrapper={<Wrapper />}
  >
  <Step1 />
  <Step2 />
  <Step3 />
</Wizard>

You can use handleStep to intercept the nextStep() call. This is useful for performing validation or saving data before allowing the user to proceed. The handler can be a synchronous function, an asynchronous function returning a Promise<void>, or null to remove the handler.

While the handler is running, isLoading will be true.

// Example: Async validation before proceeding
handleStep(async () => {
  const isValid = await validateForm();
  if (!isValid) {
    throw new Error('Invalid form data');
  }
});

// To clear the handler
handleStep(null);