NextStep is a lightweight onboarding library for Next.js / React applications. It utilizes motion for smooth animations and supports multiple React frameworks including Next.js, React Router, and Remix.
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.
The library allows users to use custom cards (tooltips) for easier integration.
If you like the project, please leave a star! ⭐️⭐️⭐️⭐️⭐️
# npm
npm i nextstepjs motion
# pnpm
pnpm add nextstepjs motion
# yarn
yarn add nextstepjs motion
# bun
bun add nextstepjs motionNextStep 2.0 introduces a framework-agnostic routing system through navigation adapters. Each adapter is packaged separately to minimize bundle size - only the adapter you import will be included in your bundle.
Important: Make sure to import the adapter you need in your app in order to access full functionality. Without an adapter, navigation features like
nextRouteandprevRoutemay not work properly.
NextStep uses Next.js adapter as default, therefore you don't need to import it.
// app/layout.tsx or pages/_app.tsximport{NextStep,NextStepProvider}from'nextstepjs';exportdefaultfunctionLayout({ children }){return(<NextStepProvider><NextStepsteps={steps}>{children}</NextStep></NextStepProvider>);}//app/root.tsximport{NextStepProvider,NextStepReact,typeTour}from'nextstepjs';import{useReactRouterAdapter}from'nextstepjs/adapters/react-router';exportdefaultfunctionApp(){return(<NextStepProvider><NextStepReactnavigationAdapter={useReactRouterAdapter}steps={steps}><Outlet/></NextStepReact></NextStepProvider>);}// root.tsximport{NextStepProvider,NextStepReact}from'nextstepjs';import{useRemixAdapter}from'nextstepjs/adapters/remix';exportdefaultfunctionApp(){return(<NextStepProvider><NextStepReactnavigationAdapter={useRemixAdapter}steps={steps}><Outlet/></NextStepReact></NextStepProvider>);}If you're using Vite with React Router or Remix, add the following configuration to your vite.config.ts:
exportdefaultdefineConfig({ssr: {noExternal: ['nextstepjs','motion'],},});Vite also requires next/navigation to be mocked in order to work properly.
- Create a mock file for
Next, such asnext-navigation.ts, and place it in/src/mocks
// Mock for Next.js navigation to prevent build errors with nextstepjs// This file is used to mock Next.js imports when using nextstepjs in a Vite appexportconstuseRouter=()=>{return{push: ()=>{},replace: ()=>{},prefetch: ()=>{},back: ()=>{},forward: ()=>{},refresh: ()=>{},};};exportconstusePathname=()=>{return'';};exportconstuseSearchParams=()=>{returnnewURLSearchParams();};exportconstuseParams=()=>{return{};};- Update
vite.config.mtsto use the proper alias for Next.js navigation imports
importpathfrom'node:path';import{defineConfig}from'vite';importreactfrom'@vitejs/plugin-react';exportdefaultdefineConfig({plugins: [react()],resolve: {alias: [// Mock Next.js navigation imports that nextstepjs might try to access{find: 'next/navigation',replacement: path.join(process.cwd(),'src/mocks/next-navigation.ts'),},],},});You can create your own navigation adapter for any routing solution by implementing the NavigationAdapter interface:
import{NextStepReact}from'nextstepjs';importtype{NavigationAdapter}from'nextstepjs';constuseCustomAdapter=(): NavigationAdapter=>{return{push: (path: string)=>{// Your navigation logic here// Example: history.push(path)},getCurrentPath: ()=>{// Your path retrieval logic here// Example: window.location.pathnamereturnwindow.location.pathname;},};};constApp=()=>{return(<NextStepReactnavigationAdapter={useCustomAdapter}steps={steps}>{children}</NextStepReact>);};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} */constnextConfig={reactStrictMode: true,experimental: {esmExternals: true,},transpilePackages: ['nextstepjs'],};exportdefaultnextConfig;You can create a custom card component for greater control over the design:
| Prop | Type | Description |
|---|---|---|
step | Object | The current Step object from your steps array, including content, title, etc. |
currentStep | number | The index of the current step in the steps array. |
totalSteps | number | The total number of steps in the onboarding process. |
nextStep | A function to advance to the next step in the onboarding process. | |
prevStep | A function to go back to the previous step in the onboarding process. | |
arrow | Returns an SVG object, the orientation is controlled by the steps side prop | |
skipTour | A function to skip the tour |
'use client';importtype{CardComponentProps}from'nextstepjs';exportconstCustomCard=({
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><buttononClick={prevStep}>Previous</button><buttononClick={nextStep}>Next</button><buttononClick={skipTour}>Skip</button>{arrow}</div>);};By default NextStep renders a small SVG caret pointing from the card to the highlighted element. You can recolor/resize it with arrowStyle, or replace it entirely with arrowComponent. Both are provider-level props and fully optional (omit them for the default arrow).
import{NextStep}from'nextstepjs';importtype{ArrowComponentProps}from'nextstepjs';// Tweak the built-in caret:<NextStepsteps={steps}arrowStyle={{color: '#6d28d9'}}>{children}</NextStep>;// Or fully replace it. Spread the provided `style` so it stays anchored to the card,// and use `side` (the resolved placement, after any cut-off adjustment) to orient it:constMyArrow=({ side, style }: ArrowComponentProps)=>(<divstyle={{ ...style}}data-side={side}>
◆
</div>);<NextStepsteps={steps}arrowComponent={MyArrow}>{children}</NextStep>;NextStep supports multiple "tours", allowing you to create multiple product tours:
import{Tour}from'nextstepjs';conststeps: Tour[]=[{tour: 'firstTour',steps: [// Step objects],},{tour: 'secondTour',steps: [// Step objects],},];| Prop | Type | Description |
|---|---|---|
icon | React.ReactNode, string, null | Optional. An icon or element to display alongside the step title (used by the default card). |
title | string | The title of your step |
content | React.ReactNode | The main content or body of the step. |
selector | string | Optional. A string used to target an id that this step refers to. If not provided, card will be displayed in the center top of the document body. |
side | "top", "bottom", "left", "right" (+ corner variants, e.g. "top-left") | Optional. Determines where the tooltip should appear relative to the selector. |
showControls | boolean | Optional. Determines whether control buttons (next, prev) should be shown if using the default card. Ignored when a custom cardComponent is provided. |
showSkip | boolean | Optional. Determines whether skip button should be shown if using the default card. Ignored when a custom cardComponent is provided. |
blockKeyboardControl | boolean | Optional. Determines whether keyboard control should be blocked |
pointerPadding | number | Optional. The padding around the pointer (keyhole) highlighting the target element. |
pointerRadius | number | Optional. The border-radius of the pointer (keyhole) highlighting the target element. |
cardOffset | number | Optional. Gap in pixels between the card and the spotlight highlight; the caret scales with it too (default: 25). |
scrollOffset | number | Optional. Extra clearance in pixels kept above/below the target when it is scrolled into view — useful when a fixed/sticky header would cover it (default: 0). |
selectorRetryAttempts | number | Optional. Extra attempts to find selector when it is missing on the first lookup (for asynchronously rendered targets). 0 keeps the single-lookup behavior (default: 0). |
selectorRetryDelay | number | Optional. Delay in milliseconds between selector retry attempts (default: 200). |
disableInteraction | boolean | Optional. If true, prevents interaction with the highlighted element (default: false). |
nextRoute | string | Optional. The route to navigate to when moving to the next step. |
prevRoute | string | Optional. The route to navigate to when moving to the previous step. |
viewportID | string | Optional. The id of the viewport element to use for positioning. If not provided, the document body will be used. |
Note
NextStephandles card cutoff from screen sides. When the requested side does not have room, NextStep verifies the destination side actually has space before flipping, and otherwise falls back to the side with the most room — so the card stays on-screen instead of swapping into another cramped edge.
Target anything in your app using the element's id attribute.
<divid="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.
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:
<divclassName="relative overflow-auto h-64"><NextStepViewportid="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',},],},];| Property | Type | Description |
|---|---|---|
children | React.ReactNode | Your website or application content |
steps | Array[] | Array of Tour objects defining each step of the onboarding |
navigationAdapter | NavigationAdapter | Optional. Router adapter for navigation (defaults to Next.js on NextStep and window adapter on NextStepReact) |
showNextStep | boolean | Controls visibility of the onboarding overlay |
shadowRgb | string | RGB values for the shadow color surrounding the target area |
shadowOpacity | string | Opacity value for the shadow surrounding the target area |
cardComponent | React.ComponentType | Custom card component to replace the default one |
cardTransition | Transition | Motion transition object for step transitions |
onStart | (tourName: string | null) => void | Callback function triggered when the tour starts |
onStepChange | (step: number, tourName: string | null) => void | Callback function triggered when the step changes |
onComplete | (tourName: string | null) => void | Callback function triggered when the tour completes |
onSkip | (step: number, tourName: string | null) => void | Callback function triggered when the user skips the tour |
clickThroughOverlay | boolean | Optional. If true, overlay background is clickable, default is false |
disableConsoleLogs | boolean | Optional. If true, console logs are disabled, default is false |
scrollToTop | boolean | Optional. If true, the page will scroll to the top when the tour ends, default is true |
noInViewScroll | boolean | Optional. If true, the page will not scroll to the target element when it is in view, default is false |
overlayZIndex | number | Optional. Base z-index for overlay elements, useful for compatibility with UI libraries like MUI (default: 999) |
arrowComponent | React.ComponentType<ArrowComponentProps> | Optional. Render a fully custom arrow/caret. Receives the resolved side and the computed positioning style. When omitted, the built-in SVG arrow is used. |
arrowStyle | React.CSSProperties | Optional. Styles merged into the built-in arrow SVG (ignored when arrowComponent is set). Handy for tweaking the caret color or size. |
Note When a custom
cardComponentis provided, the per-stepshowControls/showSkipoptions only affect the built-in card, so they are ignored (and TypeScript omits them from the step type). Your custom card renders its own controls.
<NextStepsteps={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}overlayZIndex={1400}// Set higher for MUI compatibility (MUI dialogs use 1300)>{children}</NextStep>useNextStep hook allows you to control the tour from anywhere in your app.
import{useNextStep}from'nextstepjs';
....const{ startNextStep, closeNextStep }=useNextStep();constonClickHandler=(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.