NextStep

NextStep 2.0 uses framework-agnostic navigation adapters to handle routing. Each adapter is packaged separately to minimize bundle size. You must import the specific adapter for your framework to ensure features like nextRoute and prevRoute work correctly.

Next.js

Next.js is the default adapter for the NextStep component, so no manual import is required.

import { NextStep, NextStepProvider } from 'nextstepjs';

export default function Layout({ children }) {
  return (
    <NextStepProvider>
      <NextStep steps={steps}>{children}</NextStep>
    </NextStepProvider>
  );
}

React Router

Use NextStepReact combined with the useReactRouterAdapter from nextstepjs/adapters/react-router.

import { NextStepProvider, NextStepReact } from 'nextstepjs';
import { useReactRouterAdapter } from 'nextstepjs/adapters/react-router';

export default function App() {
  return (
    <NextStepProvider>
      <NextStepReact navigationAdapter={useReactRouterAdapter} steps={steps}>
        <Outlet />
      </NextStepReact>
    </NextStepProvider>
  );
}

Remix

Use NextStepReact combined with the useRemixAdapter from nextstepjs/adapters/remix.

import { NextStepProvider, NextStepReact } from 'nextstepjs';
import { useRemixAdapter } from 'nextstepjs/adapters/remix';

export default function App() {
  return (
    <NextStepProvider>
      <NextStepReact navigationAdapter={useRemixAdapter} steps={steps}>
        <Outlet />
      </NextStepReact>
    </NextStepProvider>
  );
}

If using Vite with React Router or Remix, you must perform two steps to prevent build errors:

1. Configure SSR and Mock Next.js Navigation: Add nextstepjs and motion to noExternal in your vite.config.ts. You also need to mock next/navigation because NextStepjs may attempt to access it.

2. Create a Mock File: Create /src/mocks/next-navigation.ts with the following content:

export const useRouter = () => ({
  push: () => {},
  replace: () => {},
  prefetch: () => {},
  back: () => {},
  forward: () => {},
  refresh: () => {},
});

export const usePathname = () => '';
export const useSearchParams = () => new URLSearchParams();
export const useParams = () => ({});

3. Update Vite Alias: Update vite.config.mts to alias next/navigation to your mock file.

import path from 'node:path';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  ssr: {
    noExternal: ['nextstepjs', 'motion'],
  },
  plugins: [react()],
  resolve: {
    alias: [
      {
        find: 'next/navigation',
        replacement: path.join(process.cwd(), 'src/mocks/next-navigation.ts'),
      },
    ],
  },
});

export default defineConfig({
  ssr: {
    noExternal: ['nextstepjs', 'motion'],
  },
  // ... alias configuration
});

To gain full control over the design of the onboarding card, provide a cardComponent to the NextStep or NextStepReact component. Your component must implement the CardComponentProps interface.

Available Props:

• step: The current Step object (contains icon, title, content, etc.).
• currentStep: The index of the current step.
• totalSteps: Total number of steps.
• nextStep: Function to advance to the next step.
• prevStep: Function to go back to the previous step.
• arrow: An SVG object for the pointer (orientation controlled by side).
• skipTour: Function to skip the tour.

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

export const CustomCard = ({
  step,
  currentStep,
  totalSteps,
  nextStep,
  prevStep,
  skipTour,
  arrow,
}: CardComponentProps) => {
  return (
    <div className="my-custom-card">
      <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>
  );
};

You can customize the default SVG caret using arrowStyle or replace it entirely with arrowComponent on the NextStep component.

Tweak the built-in caret

Use arrowStyle to pass CSS properties (like color or size) to the existing SVG.

<NextStep steps={steps} arrowStyle={{ color: '#6d28d9' }}>
  {children}
</NextStep>

Replace the arrow entirely

Provide a component to arrowComponent. The component receives side (the resolved placement) and style (the computed positioning). Important: You must spread the provided style so the arrow remains anchored to the card.

const MyArrow = ({ side, style }: ArrowComponentProps) => (
  <div style={{ ...style }} data-side={side}>
    ◆
  </div>
);

<NextStep steps={steps} arrowComponent={MyArrow}>
  {children}
</NextStep>

const MyArrow = ({ side, style }: ArrowComponentProps) => (
  <div style={{ ...style }} data-side={side}>
    ◆
  </div>
);

<NextStep steps={steps} arrowComponent={MyArrow}>
  {children}
</NextStep>;