nextstepjs

NextStep is a lightweight onboarding library for Next.js applications. It utilizes framer-motion for smooth animations.

Some of the use cases:

• Easier Onboarding: Guide new users with step-by-step tours
• Engagement Boost: Make help docs interactive, so users learn by doing.
• Better Error Handling: Skip generic toasters—show users exactly what to fix with tailored tours.
• Event-Based Tours: Trigger custom tours after key actions to keep users coming back.

Note NextStep now supports non-tailwindcss projects with v1.2 onwards.

The library allows users to use custom cards (tooltips) for easier integration.

If you like the project, please leave a star! ⭐️⭐️⭐️⭐️⭐️

• Demo App
• Demo repository

# npm
npm i nextstepjs framer-motion
# pnpm
pnpm add nextstepjs framer-motion
# yarn
yarn add nextstepjs framer-motion
# bun
bun add nextstepjs framer-motion

Wrap your application in NextStepProvider and supply the steps array to NextStep.

<NextStepProvider>
  <NextStep steps={steps}>{children}</NextStep>
</NextStepProvider>

Wrap your application in NextStepProvider and supply the steps array to NextStep.

<NextStepProvider>
  <NextStep steps={steps}>
    <Component {...pageProps} />
  </NextStep>
</NextStepProvider>

If you encounter an error related to module exports when using the Pages Router, it is likely due to a mismatch between ES modules (which use export statements) and CommonJS modules (which use module.exports). The nextstepjs package uses ES module syntax, but your Next.js project might be set up to use CommonJS.

To resolve this issue, ensure that your Next.js project is configured to support ES modules. You can do this by updating your next.config.js file to include the following configuration:

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  experimental: {
    esmExternals: true,
  },
  transpilePackages: ['nextstepjs'],
};

export default nextConfig;

You can create a custom card component for greater control over the design:

'use client';
import type { CardComponentProps } from 'nextstepjs';

export const CustomCard = ({
  step,
  currentStep,
  totalSteps,
  nextStep,
  prevStep,
  skipTour,
  arrow,
}: CardComponentProps) => {
  return (
    <div>
      <h1>
        {step.icon} {step.title}
      </h1>
      <h2>
        {currentStep} of {totalSteps}
      </h2>
      <p>{step.content}</p>
      <button onClick={prevStep}>Previous</button>
      <button onClick={nextStep}>Next</button>
      <button onClick={skipTour}>Skip</button>
      {arrow}
    </div>
  );
};

NextStep supports multiple "tours", allowing you to create multiple product tours:

import { Tour } from 'nextstepjs';

const steps: Tour[] = [
  {
    tour: 'firstTour',
    steps: [
      // Step objects
    ],
  },
  {
    tour: 'secondTour',
    steps: [
      // Step objects
    ],
  },
];

Note NextStep handles card cutoff from screen sides. If side is right or left and card is out of the viewport, side would be switched to top. If side is top or bottom and card is out of the viewport, then side would be flipped between top and bottom.

Target anything in your app using the element's id attribute.

<div id="nextstep-step1">Onboard Step</div>

NextStep allows you to navigate between different routes during a tour using the nextRoute and prevRoute properties in the step object. These properties enable seamless transitions between different pages or sections of your application.

• nextRoute: Specifies the route to navigate to when the "Next" button is clicked.
• prevRoute: Specifies the route to navigate to when the "Previous" button is clicked.

When nextRoute or prevRoute is provided, NextStep will use Next.js's next/navigation to navigate to the specified route.

Only available after > v1.1.x When a selector is in a scrollable area, it is best to wrap the content of the scrollable area with NextStepViewport. This component takes children and an id as prop. By providing the viewportID to the step, NextStep will target this element within the viewport. This ensures that the step is anchored to the element even if the container is scrollable.

Here's an example of how to use NextStepViewport:

<div className="relative overflow-auto h-64">
  <NextStepViewport id="scrollable-viewport">{children}</NextStepViewport>
</div>

[
  {
    tour: 'firsttour',
    steps: [
      {
        icon: <>👋</>,
        title: 'Tour 1, Step 1',
        content: <>First tour, first step</>,
        selector: '#tour1-step1',
        side: 'top',
        showControls: true,
        showSkip: true,
        pointerPadding: 10,
        pointerRadius: 10,
        nextRoute: '/foo',
        prevRoute: '/bar',
      },
      {
        icon: <>🎉</>,
        title: 'Tour 1, Step 2',
        content: <>First tour, second step</>,
        selector: '#tour1-step2',
        side: 'top',
        showControls: true,
        showSkip: true,
        pointerPadding: 10,
        pointerRadius: 10,
        viewportID: 'scrollable-viewport',
      },
    ],
  },
  {
    tour: 'secondtour',
    steps: [
      {
        icon: <>🚀</>,
        title: 'Second tour, Step 1',
        content: <>Second tour, first step!</>,
        selector: '#nextstep-step1',
        side: 'top',
        showControls: true,
        showSkip: true,
        pointerPadding: 10,
        pointerRadius: 10,
        nextRoute: '/foo',
        prevRoute: '/bar',
      },
    ],
  },
];

<NextStep
  steps={steps}
  showNextStep={true}
  shadowRgb="55,48,163"
  shadowOpacity="0.8"
  cardComponent={CustomCard}
  cardTransition={{ duration: 0.5, type: 'spring' }}
  onStepChange={(step, tourName) => console.log(`Step changed to ${step} in ${tourName}`)}
  onComplete={(tourName) => console.log(`Tour completed: ${tourName}`)}
  onSkip={(step, tourName) => console.log(`Tour skipped: ${step} in ${tourName}`)}
  clickThroughOverlay={false}
>
  {children}
</NextStep>

useNextStep hook allows you to control the tour from anywhere in your app.

import { useNextStep } from 'nextstepjs';
....

const { startNextStep, closeNextStep } = useNextStep();

const onClickHandler = (tourName: string) => {
  startNextStep(tourName);
};

NextStep supports keyboard navigation:

• Right Arrow: Next step
• Left Arrow: Previous step
• Escape: Skip tour

NextStep is a lightweight library and does not come with localization support. However, you can easily switch between languages by supplying the steps array based on locale.

Contributions are welcome! Please feel free to submit a Pull Request.

This project is licensed under the MIT License.

• Onborda for the inspiration and some code snippets.