Tour Steps for Next.js

Learn how to create tour steps for your Next.js project. This guide will walk you through the step configuration options and provide examples.

Step Object Properties

Each step in your tour is defined by a step object with the following properties:

Step Object Properties
Property	Type	Description
icon	`React.ReactNode \| string \| null`	An icon or element to display alongside the step title.
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" \| "top-left" \| "top-right" \| "bottom-left" \| "bottom-right"`	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.
showSkip	`boolean`	Optional. Determines whether skip button should be shown if using the default card.
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.
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: 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.

Tours Array

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
    ],
  },
];

Example Steps

Here's an example of a complete steps array with multiple tours:

import { Tour } from 'nextstepjs';

const steps: Tour[] = [
  {
    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',
      },
    ],
  },
];

export default steps;

Targeting Elements

Target any element in your app using the element's id attribute. The selector property in your step should match the id of the element you want to target.

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

Interactive Demo

Here's an interactive demo of a tour with two steps. Click the button below to start the tour.

This is the first step (ID: docs-demo-step1)

This is the second step (ID: docs-demo-step2)

// In your steps.tsx file
{
  tour: 'docs-demo',
  steps: [
    {
      icon: <>👋</>,
      title: 'First Step',
      content: <>This is the first step of our demo tour</>,
      selector: '#docs-demo-step1',
      side: 'bottom',
      showControls: true,
      showSkip: true,
      pointerPadding: 10,
      pointerRadius: 10,
    },
    {
      icon: <>🎉</>,
      title: 'Second Step',
      content: <>This is the second step of our demo tour</>,
      selector: '#docs-demo-step2',
      side: 'bottom',
      showControls: true,
      showSkip: true,
      pointerPadding: 10,
      pointerRadius: 10,
    },
  ],
},

// In your component
import { useNextStep } from 'nextstepjs';

const YourComponent = () => {
  const { startNextStep } = useNextStep();
  
  return (
    <Button onClick={() => startNextStep('docs-demo')}>
      Start Demo Tour
    </Button>
  );
};