NextStep for React

https://nextstepjs.com/docs/react
Admin
NextStep is a lightweight library for React applications, designed to help developers implement user...
Tokens:21,976
Snippets:212
Trust Score:5.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### onStart Callback Example

Source: https://nextstepjs.com/docs/react-router/callbacks

Called when a tour begins. Accepts the tour name. Useful for tracking tour starts or initializing tour-related state.

```typescript
onStart: (tourName: string | null) => {
  console.log(`Tour ${tourName} started`);
  // Track analytics, set user state, etc.
}
```

--------------------------------

### Install NextStep and Motion with npm

Source: https://nextstepjs.com/docs/react-router

Use this command to install the necessary packages with npm.

```bash
npm i nextstepjs motion
```

--------------------------------

### Install NextStep and Motion with bun

Source: https://nextstepjs.com/docs/react-router

Use this command to install the necessary packages with bun.

```bash
bun add nextstepjs motion
```

--------------------------------

### Start Tour in React Component

Source: https://nextstepjs.com/docs/react/tour-steps

Shows how to use the `useNextStep` hook to get the `startNextStep` function and trigger the tour from a button click.

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

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

--------------------------------

### Install NextStep and Motion with yarn

Source: https://nextstepjs.com/docs/react-router

Use this command to install the necessary packages with yarn.

```bash
yarn add nextstepjs motion
```

--------------------------------

### Install NextStep and Motion with pnpm

Source: https://nextstepjs.com/docs/react-router

Use this command to install the necessary packages with pnpm.

```bash
pnpm add nextstepjs motion
```

--------------------------------

### Quick Snap Animation Example

Source: https://nextstepjs.com/docs/react-router/animations

Example configuration for a quick snap animation using backOut ease.

```javascript
cardTransition={{ 
  ease: 'backOut', 
  duration: 0.3 
}}
```

--------------------------------

### Basic Usage of useNextStep Hook

Source: https://nextstepjs.com/docs/react-router/useNextStep

Import and use the useNextStep hook to get functions for starting and closing tours. Call startNextStep with a tour name to initiate a specific tour.

```javascript
import { useNextStep } from 'nextstepjs';

function YourComponent() {
  const { startNextStep, closeNextStep } = useNextStep();
  
  const handleStartTour = () => {
    startNextStep('tourName');
  };
  
  const handleCloseTour = () => {
    closeNextStep();
  };
  
  return (
    <div>
      <button onClick={handleStartTour}>Start Tour</button>
      <button onClick={handleCloseTour}>Close Tour</button>
    </div>
  );
}
```

--------------------------------

### Practical Example: Help Button

Source: https://nextstepjs.com/docs/react-router/useNextStep

Integrate the useNextStep hook into a UI component to create an interactive button that triggers a specific tour. This example uses a custom Button component.

```javascript
'use client';

import { useNextStep } from 'nextstepjs';
import { Button } from '@/components/ui/button';
import { HelpCircle } from 'lucide-react';

export function HelpButton() {
  const { startNextStep } = useNextStep();
  
  return (
    <Button
      variant="outline"
      size="icon"
      onClick={() => startNextStep('helpTour')}
      aria-label="Help"
    >
      <HelpCircle className="h-4 w-4" />
    </Button>
  );
}
```

--------------------------------

### Complete useNextStep Hook Example

Source: https://nextstepjs.com/docs/react-router/useNextStep

A comprehensive example demonstrating the usage of all methods and properties provided by the useNextStep hook for full tour control within a component.

```javascript
'use client';
import { useNextStep } from 'nextstepjs';

export default function TourController() {
  const { 
    startNextStep, 
    closeNextStep, 
    currentTour, 
    currentStep, 
    setCurrentStep, 
    isNextStepVisible 
  } = useNextStep();

  const handleStartTour = () => {
    startNextStep('welcomeTour');
  };

  const handleSkipTour = () => {
    closeNextStep();
  };

  const handleJumpToStep = () => {
    setCurrentStep(2);
  };

  return (
    <div className="tour-controls">
      <button onClick={handleStartTour}>Start Tour</button>
      
      {isNextStepVisible && (
        <>
          <button onClick={handleSkipTour}>Skip Tour</button>
          <button onClick={handleJumpToStep}>Jump to Step 3</button>
          <div className="tour-status">
            <p>Current tour: {currentTour}</p>
            <p>Current step: {currentStep + 1}</p>
          </div>
        </>
      )}
    </div>
  );
}
```

--------------------------------

### Basic React Setup with NextStepProvider

Source: https://nextstepjs.com/docs/react/basic-setup

Wrap your application with NextStepProvider and NextStepReact, supplying the steps array. Ensure your app content is nested within these providers.

```javascript
import { NextStepProvider, NextStepReact } from 'nextstepjs';

const steps = [
  {
    tour: "mainTour",
    steps: [
      {
        icon: "👋",
        title: "Welcome",
        content: "Let's get started with NextStep!",
        selector: "#step1",
        side: "right",
        showControls: true,
        showSkip: true
      },
      // More steps...
    ]
  }
];

function App() {
  return (
    <NextStepProvider>
      <NextStepReact steps={steps}>
        <YourAppContent />
      </NextStepReact>
    </NextStepProvider>
  );
}
```

--------------------------------

### Start Tour from Component

Source: https://nextstepjs.com/docs/react-router/tour-steps

Initiates a NextStep.js tour from a React component. It uses the `useNextStep` hook to get the `startNextStep` function, which is then called with the tour's unique identifier.

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

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

```

--------------------------------

### Basic NextStepProvider Setup in React

Source: https://nextstepjs.com/docs/react/routing

This snippet shows the basic setup for NextStep in a root React component using NextStepProvider and NextStepReact. Ensure NextStepProvider wraps your application or the part using NextStep.

```javascript
import { NextStepProvider, NextStepReact } from 'nextstepjs';
import steps from './steps';

function App() {
  return (
    <NextStepProvider>
      <NextStepReact steps={steps}>
        <YourAppContent />
      </NextStepReact>
    </NextStepProvider>
  );
}
```

--------------------------------

### Bouncy Spring Animation Example

Source: https://nextstepjs.com/docs/react-router/animations

Example configuration for a bouncy spring animation with specified stiffness and damping.

```javascript
cardTransition={{ 
  type: 'spring',
  stiffness: 300,
  damping: 20
}}
```

--------------------------------

### Complete Example Steps Array

Source: https://nextstepjs.com/docs/react-router/tour-steps

Provides a comprehensive example of a steps array with multiple tours and detailed step configurations, including icons, titles, content, selectors, side positioning, controls, and routing.

```typescript
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;
```

--------------------------------

### Start a Specific Tour

Source: https://nextstepjs.com/docs/react-router/useNextStep

Use the startNextStep function to initiate a tour by its unique name. If no name is provided, it defaults to starting the first tour defined in your steps.

```javascript
// Start a specific tour
startNextStep('tourName');
```

--------------------------------

### Delayed Appearance Animation Example

Source: https://nextstepjs.com/docs/react-router/animations

Example configuration for an animation with a delayed appearance.

```javascript
cardTransition={{ 
  ease: 'easeOut', 
  duration: 0.4,
  delay: 0.2
}}
```

--------------------------------

### Quick Snap Animation Example

Source: https://nextstepjs.com/docs/react/animations

Create a quick snap animation for tour steps using 'backOut' easing and a short duration of 0.3 seconds.

```javascript
cardTransition={{
  ease: 'backOut',
  duration: 0.3
}}
```

--------------------------------

### Smooth Fade Animation Example

Source: https://nextstepjs.com/docs/react/animations

Configure a smooth fade-in/out animation for tour steps using 'easeInOut' timing and a duration of 0.5 seconds.

```javascript
cardTransition={{ 
  ease: 'easeInOut', 
  duration: 0.5 
}}
```

--------------------------------

### Delayed Appearance Animation Example

Source: https://nextstepjs.com/docs/react/animations

Add a slight delay before the animation starts for tour steps by setting the 'delay' property to 0.2 seconds.

```javascript
cardTransition={{
  ease: 'easeOut',
  duration: 0.4,
  delay: 0.2
}}
```

--------------------------------

### Conditional Tour Start with useEffect

Source: https://nextstepjs.com/docs/react-router/useNextStep

Use the useEffect hook in conjunction with useNextStep to automatically start a tour when specific conditions are met, such as for new user onboarding.

```javascript
'use client';

import { useEffect } from 'react';
import { useNextStep } from 'nextstepjs';

export function OnboardingWrapper({ children, isNewUser }) {
  const { startNextStep } = useNextStep();
  
  useEffect(() => {
    // Start the onboarding tour for new users
    if (isNewUser) {
      startNextStep('onboardingTour');
    }
  }, [isNewUser, startNextStep]);
  
  return <>{children}</>;
}
```

--------------------------------

### useNextStep Hook

Source: https://nextstepjs.com/docs/react-router/api

Provides programmatic control over the tour, allowing you to start, stop, skip, or navigate through steps.

```APIDOC
## useNextStep Hook

### Description
The `useNextStep` hook provides programmatic control over the tour. You can use it to start, stop, skip, or navigate through steps.

### Return Values
- **startNextStep** ( (tourName: string) => void ) - Starts the specified tour
- **closeNextStep** ( () => void ) - Stops the current tour
- **currentTour** ( string | null ) - The name of the current tour
- **currentStep** ( number ) - The current step index
- **setCurrentStep** ( (step: number, delay?: number) => void ) - Sets the current step index with optional delay
- **isNextStepVisible** ( boolean ) - Whether the tour overlay is currently visible
```

--------------------------------

### onSkip Callback Example

Source: https://nextstepjs.com/docs/react-router/callbacks

Fires when a user chooses to skip the tour. Receives the current step index and tour name. Useful for logging skip events.

```typescript
onSkip: (step: number, tourName: string | null) => {
  console.log(`Tour ${tourName} skipped at step ${step}`);
  // Log skip event, offer to resume later, etc.
}
```

--------------------------------

### React Router Setup with NextStepProvider

Source: https://nextstepjs.com/docs/react-router/basic-setup

Wrap your application with NextStepProvider and NextStepReact, providing the React Router adapter and tour steps. This is the main entry point for NextStep.js in a React Router application.

```tsx
//app/root.tsx
import { NextStepProvider, NextStepReact } from 'nextstepjs';
import { useReactRouterAdapter } from 'nextstepjs/adapters/react-router';
import { Outlet } from 'react-router-dom';

const steps = [
  {
    tour: "mainTour",
    steps: [
      {
        icon: "👋",
        title: "Welcome",
        content: "Let's get started with NextStep!",
        selector: "#step1",
        side: "right",
        showControls: true,
        showSkip: true
      },
      // More steps...
    ]
  }
];

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

```

--------------------------------

### Async Validation Example

Source: https://nextstepjs.com/docs/react-router/validation

Perform asynchronous validation by making an API call. This example fetches data from an endpoint to determine the validity status.

```javascript
const asyncValidation = {
  validation: async () => {
    try {
      const response = await fetch('/api/validate-user');
      const data = await response.json();
      return data.isValid;
    } catch (error) {
      return false;
    }
  },
  validationMessage: 'Please complete the required verification.',
};
```

--------------------------------

### onComplete Callback Example

Source: https://nextstepjs.com/docs/react-router/callbacks

Triggered when a tour is successfully finished. Accepts the tour name. Ideal for logging completion or updating user profiles.

```typescript
onComplete: (tourName: string | null) => {
  console.log(`Tour ${tourName} completed`);
  // Update user preferences, show completion message, etc.
}
```

--------------------------------

### Example Validation Configuration

Source: https://nextstepjs.com/docs/react-router/validation

Define validation rules and messages for different steps within a tour. This configuration object allows for asynchronous validation functions and custom error messages.

```typescript
interface ValidationStep {
  validation: () => boolean | Promise<boolean>;
  validationMessage: string;
}

interface ValidationTour {
  [stepIndex: number]: ValidationStep;
}

interface ValidationConfig {
  [tourName: string]: ValidationTour;
}

const validation: ValidationConfig = {
  'validation-demo': {
    0: {
      validation: async () => {
        console.log('Validating step 0');
        await new Promise((resolve) => setTimeout(resolve, 1000));
        return true;
      },
      validationMessage: 'Step 0 validation failed',
    },
    1: {
      validation: () => {
        console.log('Validating step 1');
        // Check window width return true if width is greater than 768
        return window.innerWidth > 768;
      },
      validationMessage: 'Window width must be greater than 768',
    },
    2: {
      validation: () => {
        console.log('Validating step 2');
        // Check if window width is less than 768
        return window.innerWidth < 768;
      },
      validationMessage: 'Window width must be less than 768',
    },
  },
};

export default validation;

```

--------------------------------

### Tracking User Progress with Callbacks

Source: https://nextstepjs.com/docs/react-router/callbacks

Implements analytics tracking for tour events (start, step change, completion, skip) using a callback object.

```jsx
// Track user progress with analytics
const trackProgress = {
  onStart: (tourName) => {
    analytics.track('tour_started', { tourName });
  },
  onStepChange: (step, tourName) => {
    analytics.track('tour_step_viewed', { 
      tourName,
      stepIndex: step,
      stepName: `${tourName}_step_${step}`
    });
  },
  onComplete: (tourName) => {
    analytics.track('tour_completed', { tourName });
    // Update user profile to mark onboarding as complete
    updateUserProfile({ onboardingComplete: true });
  },
  onSkip: (step, tourName) => {
    analytics.track('tour_skipped', { tourName, stepIndex: step });
  }
};

// Then use it in your NextStep component
<NextStepReact 
  steps={steps}
  {...trackProgress}
>
  {children}
</NextStepReact>
```

--------------------------------

### onStepChange Callback Example

Source: https://nextstepjs.com/docs/react-router/callbacks

Invoked whenever the current tour step changes. Receives the new step index and tour name. Can be used for UI updates or animations.

```typescript
onStepChange: (step: number, tourName: string | null) => {
  console.log(`Tour ${tourName} moved to step ${step}`);
  // Update UI, trigger animations, etc.
}
```

--------------------------------

### Integrating NextStepjs with ThemeProvider

Source: https://nextstepjs.com/docs/react-router/dark-mode

Wrap your application with ThemeProvider and NextStepProvider to ensure NextStepjs components inherit dark mode styles. This setup is crucial for seamless dark mode support.

```javascript
import { NextStepReact, NextStepProvider } from 'nextstepjs';
import { ThemeProvider } from 'your-theme-provider';

function MyApp({ Component, pageProps }) {
  return (
    <ThemeProvider>
      <NextStepProvider>
        <NextStepReact steps={steps}>
          <Component {...pageProps} />
        </NextStepReact>
      </NextStepProvider>
    </ThemeProvider>
  );
}
```

--------------------------------

### Button Click Validation Example

Source: https://nextstepjs.com/docs/react-router/validation

Validate user interaction by checking a flag in local storage. This is useful for ensuring a user has performed a specific action, like clicking a button, before proceeding.

```javascript
const buttonClickValidation = {
  validation: () => {
    return localStorage.getItem('button-clicked') === 'true';
  },
  validationMessage: 'Please click the "Get Started" button to continue.',
};

// In your component, set the flag when button is clicked
const handleButtonClick = () => {
  localStorage.setItem('button-clicked', 'true');
  // Your button logic here
};
```

--------------------------------

### Custom Card Component with Dark Mode Support

Source: https://nextstepjs.com/docs/react-router/dark-mode

Create custom card components that dynamically adjust their appearance based on the application's dark mode state. This example uses a hypothetical theme hook to detect the current mode.

```javascript
'use client';

import React from 'react';
import { Step } from 'nextstepjs';
import { useTheme } from 'your-theme-hook'; // Your theme hook

interface DarkModeCardProps {
  step: Step;
  currentStep: number;
  totalSteps: number;
  nextStep: () => void;
  prevStep: () => void;
  skipTour: () => void;
  arrow: React.ReactNode;
}

const DarkModeCard = ({
  step,
  currentStep,
  totalSteps,
  nextStep,
  prevStep,
  skipTour,
  arrow,
}: DarkModeCardProps) => {
  const { isDarkMode } = useTheme(); // Get theme from your context
  
  return (
    <div
      className={`${isDarkMode ? 'bg-gray-800 text-white' : 'bg-white text-gray-800'} rounded-lg shadow-lg p-6 max-w-md`}
    >
      <div className="flex items-center gap-3 mb-4">
        {step.icon && <div className="text-2xl">{step.icon}</div>}
        <h3 className="text-xl font-bold">{step.title}</h3>
      </div>
      
      <div className="mb-6">{step.content}</div>
      
      {arrow}
      
      <div className="flex justify-between items-center">
        <div className="text-sm">
          Step {currentStep + 1} of {totalSteps}
        </div>
        
        <div className="flex gap-2">
          {currentStep > 0 && (
            <button
              onClick={prevStep}
              className={`px-4 py-2 ${isDarkMode ? 'bg-gray-700 text-gray-300' : 'bg-gray-200 text-gray-700'} rounded`}
            >
              Previous
            </button>
          )}
          
          <button
            onClick={nextStep}
            className={`px-4 py-2 ${isDarkMode ? 'bg-blue-600' : 'bg-blue-500'} text-white rounded`}
          >
            {currentStep === totalSteps - 1 ? 'Finish' : 'Next'}
          </button>
          
          {step.showSkip && (
            <button
              onClick={skipTour}
              className={`px-4 py-2 ${isDarkMode ? 'text-gray-400' : 'text-gray-500'}`}
            >
              Skip
            </button>
          )}
        </div>
      </div>
    </div>
  );
};

export default DarkModeCard;

```

--------------------------------

### Form Field Validation Example

Source: https://nextstepjs.com/docs/react-router/validation

Implement form field validation by checking input values. Ensure the input element exists and meets the minimum length requirement.

```javascript
const formValidation = {
  validation: () => {
    const input = document.getElementById('username') as HTMLInputElement;
    return input && input.value.length >= 3;
  },
  validationMessage: 'Please enter a username with at least 3 characters.',
};
```

--------------------------------

### Adjusting Overlay Color for Dark Mode

Source: https://nextstepjs.com/docs/react-router/dark-mode

Customize the overlay color and opacity for the NextStepJS tour when in dark mode. This example shows how to conditionally set `shadowRgb` and `shadowOpacity` based on a theme hook.

```jsx
import { useTheme } from 'your-theme-hook';

function MyApp({ Component, pageProps }) {
  const { isDarkMode } = useTheme();
  
  return (
    <NextStepProvider>
      <NextStep 
        steps={steps} 
        shadowRgb={isDarkMode ? "255, 255, 255" : "0, 0, 0"}
        shadowOpacity={isDarkMode ? "0.15" : "0.2"}
      >
        <Component {...pageProps} />
      </NextStep>
    </NextStepProvider>
  );
}

```

--------------------------------

### Custom Card Component with Shadcn UI

Source: https://nextstepjs.com/docs/react-router/styling

An example of a custom card component for NextStepjs tours utilizing Shadcn UI components for styling and layout. This component also requires the 'use client' directive.

```javascript
'use client';

import React from 'react';
import { Step } from 'nextstepjs';
import { Card, CardContent, CardFooter, CardHeader, CardTitle } from '@/components/ui/card';
import { Button } from '@/components/ui/button';

interface ShadcnCustomCardProps {
  step: Step;
  currentStep: number;
  totalSteps: number;
  nextStep: () => void;
  prevStep: () => void;
  skipTour: () => void;
  arrow: React.ReactNode;
}

const ShadcnCustomCard = ({
  step,
  currentStep,
  totalSteps,
  nextStep,
  prevStep,
  skipTour,
  arrow,
}: ShadcnCustomCardProps) => {
  return (
    <Card className="w-[350px]">
      <CardHeader>
        <CardTitle className="flex items-center gap-2">
          {step.icon && <span>{step.icon}</span>}
          {step.title}
        </CardTitle>
      </CardHeader>
      
      <CardContent>
        <div className="mb-2">{step.content}</div>
        {arrow}
      </CardContent>
      
      <CardFooter className="flex justify-between">
        <div className="text-sm text-muted-foreground">
          {currentStep + 1} / {totalSteps}
        </div>
        
        <div className="flex gap-2">
          {currentStep > 0 && (
            <Button variant="outline" size="sm" onClick={prevStep}>
              Previous
            </Button>
          )}
          
          <Button size="sm" onClick={nextStep}>
            {currentStep === totalSteps - 1 ? 'Finish' : 'Next'}
          </Button>
          
          {step.showSkip && (
            <Button variant="ghost" size="sm" onClick={skipTour}>
              Skip
            </Button>
          )}
        </div>
      </CardFooter>
    </Card>
  );
};

export default ShadcnCustomCard;

```

--------------------------------

### Initializing NextStep with Callbacks

Source: https://nextstepjs.com/docs/react-router/callbacks

Demonstrates how to pass various tour callbacks directly when initializing the NextStepReact component in your application.

```jsx
import { NextStepProvider, NextStepReact } from 'nextstepjs';
import steps from './steps';

function App() {
  return (
    <NextStepProvider>
      <NextStepReact 
        steps={steps}
        onStart={(tourName) => {
          console.log(`Tour ${tourName} started`);
        }}
        onComplete={(tourName) => {
          console.log(`Tour ${tourName} completed`);
        }}
        onSkip={(step, tourName) => {
          console.log(`Tour ${tourName} skipped at step ${step}`);
        }}
        onStepChange={(step, tourName) => {
          console.log(`Step changed to ${step} in ${tourName}`);
        }}
      >
        <YourAppContent />
      </NextStepReact>
    </NextStepProvider>
  );
}
```

--------------------------------

### NextStepReact Component Props

Source: https://nextstepjs.com/docs/react-router/api

The main component that wraps your application and provides the onboarding functionality. It accepts various props to customize the tour experience.

```APIDOC
## NextStepReact Component Props

### Description
The `NextStepReact` component is the main component that wraps your application and provides the onboarding functionality.

### Props
- **children** (React.ReactNode) - Required - Your website or application content
- **steps** (Tour[]) - Required - Array of Tour objects defining each step of the onboarding
- **navigationAdapter** (NavigationAdapter) - Optional - Router adapter for navigation (defaults to window adapter)
- **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) - Framer 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) - 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 starts, 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 that use high z-index values (default: 997)
```

--------------------------------

### React Routing Demo Configuration

Source: https://nextstepjs.com/docs/react/routing

Defines the steps for an interactive routing demo in a React application using NextStep.js. Each step includes navigation logic using `nextRoute` and `prevRoute`.

```typescript
// In your steps.tsx file
{
  tour: 'react-routing-demo',
  steps: [
    {
      icon: <>👋</>,
      title: 'Routing Demo',
      content: <>This is the first step of our routing demo. Click next to navigate to the homepage.</>,
      selector: '#routing-demo-step',
      side: 'bottom',
      showControls: true,
      showSkip: true,
      nextRoute: '/',
    },
    {
      icon: <>❤️</>,
      title: 'Support the Developer',
      content: <>We've navigated to the homepage. Please consider supporting the developer if you find NextStep useful. <br /> <br /> Click next to navigate back to the routing documentation.</>,
      selector: '#buy-me-a-coffee-button',
      side: 'right',
      showControls: true,
      showSkip: true,
      prevRoute: '/docs/react/routing',
      nextRoute: '/docs/react/routing',
    },
    {
      icon: <>🎉</>,
      title: 'Back to Docs',
      content: <>We've navigated back to the routing documentation. You've completed the routing demo!</>,
      selector: '#routing-demo-step',
      side: 'bottom',
      showControls: true,
      showSkip: true,
      prevRoute: '/',
    },
  ],
}
```

--------------------------------

### React Router Routing Demo Configuration

Source: https://nextstepjs.com/docs/react-router/routing

Configure tour steps for a React Router demo. Use `nextRoute` and `prevRoute` to control navigation. NextStep waits for the target element to be found on the new route before displaying the step.

```typescript
// In your steps.tsx file
{
  tour: 'react router-routing-demo',
  steps: [
    {
      icon: <>
        👋
      </>,
      title: 'Routing Demo',
      content: <>
        This is the first step of our routing demo. Click next to navigate to the homepage.
      </>,
      selector: '#routing-demo-step',
      side: 'bottom',
      showControls: true,
      showSkip: true,
      nextRoute: '/',
    },
    {
      icon: <>
        ❤️
      </>,
      title: 'Support the Developer',
      content: <>
        We've navigated to the homepage. Please consider supporting the developer if you find NextStep useful. <br /> <br /> Click next to navigate back to the routing documentation.
      </>,
      selector: '#buy-me-a-coffee-button',
      side: 'right',
      showControls: true,
      showSkip: true,
      prevRoute: '/docs/react-router/routing',
      nextRoute: '/docs/react-router/routing',
    },
    {
      icon: <>
        🎉
      </>,
      title: 'Back to Docs',
      content: <>
        We've navigated back to the routing documentation. You've completed the routing demo!
      </>,
      selector: '#routing-demo-step',
      side: 'bottom',
      showControls: true,
      showSkip: true,
      prevRoute: '/',
    },
  ],
}
```

--------------------------------

### Initializing NextStep with Callbacks in React

Source: https://nextstepjs.com/docs/react/callbacks

Demonstrates how to pass various tour lifecycle callbacks directly to the NextStepReact component during initialization in a React application.

```typescript
// In your root component
import { NextStepProvider, NextStepReact } from 'nextstepjs';
import steps from './steps';

function App() {
  return (
    <NextStepProvider>
      <NextStepReact 
        steps={steps}
        onStart={(tourName) => {
          console.log(`Tour ${tourName} started`);
        }}
        onComplete={(tourName) => {
          console.log(`Tour ${tourName} completed`);
        }}
        onSkip={(step, tourName) => {
          console.log(`Tour ${tourName} skipped at step ${step}`);
        }}
        onStepChange={(step, tourName) => {
          console.log(`Step changed to ${step} in ${tourName}`);
        }}
      >
        <YourAppContent />
      </NextStepReact>
    </NextStepProvider>
  );
}
```

--------------------------------

### Check Current Tour Name

Source: https://nextstepjs.com/docs/react-router/useNextStep

Access the currentTour property to get the name of the active tour. This is useful for conditional logic based on which tour is currently displayed.

```javascript
// Check the current tour
if (currentTour === 'featureTour') {
  // Do something specific for this tour
}
```

--------------------------------

### Define Tour Steps

Source: https://nextstepjs.com/docs/react-router/tour-steps

Defines the configuration for a multi-step tour, including icons, titles, content, selectors, and display options for each step. This configuration is used to initialize the tour.

```typescript
// 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,
    },
  ],
},

```

--------------------------------

### Get Current Step Index

Source: https://nextstepjs.com/docs/react-router/useNextStep

Retrieve the currentStep property to know the index of the active step within the tour. This can be used for progress indicators or step-specific logic.

```javascript
// Get the current step index
console.log(`Current step: ${currentStep + 1} of ${totalSteps}`);
```

--------------------------------

### Next.js Navigation Mock for Vite

Source: https://nextstepjs.com/docs/react-router/basic-setup

Create a mock file for Next.js navigation functions when using Vite. This prevents build errors by providing dummy implementations for `useRouter`, `usePathname`, `useSearchParams`, and `useParams`.

```ts
//src/mocks/next-navigation.ts
// 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 app

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

export const usePathname = () => {
  return '';
};

export const useSearchParams = () => {
  return new URLSearchParams();
};

export const useParams = () => {
  return {};
};

```

--------------------------------

### Navigation Adapter Interface

Source: https://nextstepjs.com/docs/react/api

NextStepjs 2.0 introduces a framework-agnostic routing system through navigation adapters, allowing for custom routing logic.

```APIDOC
## Navigation Adapter

NextStepjs 2.0 introduces a framework-agnostic routing system through navigation adapters. Each adapter is packaged separately to minimize bundle size.

| Property| Type| Description  
---|---|---
push| (path: string) => void| Function to navigate to a new route  
getCurrentPath| () => string| Function to get the current route path
```

--------------------------------

### Define Tour Steps

Source: https://nextstepjs.com/docs/react/tour-steps

Defines the configuration for a two-step tour, including content, selectors, and display options for each step.

```typescript
// 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,
    },
  ],
}
```

--------------------------------

### Vite Configuration for NextStep.js

Source: https://nextstepjs.com/docs/react/basic-setup

Configure Vite to handle nextstepjs by aliasing 'next/navigation' to a mock file and ensuring 'nextstepjs' and 'motion' are not externalized during SSR.

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

export default defineConfig({
  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'),
      },
    ]
  },
  ssr: {
    noExternal: ['nextstepjs', 'motion']
  }
});
```

--------------------------------

### Customizing Tour Animations in React

Source: https://nextstepjs.com/docs/react/animations

Customize animation behavior by providing custom transition settings to the `cardTransition` prop of the `NextStepReact` component. This example shows how to integrate NextStepjs within a React application.

```javascript
import { NextStepReact, NextStepProvider } from 'nextstepjs';

function MyApp({ Component, pageProps }) {
  return (
    <NextStepProvider>
      <NextStepReact
        steps={steps}
        cardTransition={{
          ease: 'easeOut',
          duration: 0.4,
          stiffness: 100,
          damping: 10
        }}
      >
        <Component {...pageProps} />
      </NextStepReact>
    </NextStepProvider>
  );
}
```

--------------------------------

### Define Steps for Different Languages

Source: https://nextstepjs.com/docs/react/localization

Create separate steps arrays for English and Spanish. Use these arrays to dynamically set the tour steps based on the current locale in your application.

```javascript
// Define steps for different languages
const stepsEn = [
  {
    tour: 'welcome',
    steps: [
      {
        icon: <>
        👋</>,
        title: 'Welcome',
        content: <>
        This is the first step</>,
        selector: '#welcome-element',
        side: 'top',
      },
      // More steps...
    ],
  },
];

const stepsEs = [
  {
    tour: 'welcome',
    steps: [
      {
        icon: <>
        👋</>,
        title: 'Bienvenido',
        content: <>
        Este es el primer paso</>,
        selector: '#welcome-element',
        side: 'top',
      },
      // More steps...
    ],
  },
];

// Use the appropriate steps array based on locale
const MyApp = ({ locale }) => (
  <NextStepProvider>
    <NextStepReact steps={locale === 'es' ? stepsEs : stepsEn}>
      {/* Your app content */}
    </NextStepReact>
  </NextStepProvider>
);

```

--------------------------------

### Updating UI with onStepChange Callback

Source: https://nextstepjs.com/docs/react-router/callbacks

Use the `onStepChange` callback to dynamically update UI elements, such as highlighting specific sections, based on the current step and tour name. Ensure callbacks are defined in a client component with 'use client'.

```javascript
// Dynamic content based on current step
const [highlightedSection, setHighlightedSection] = useState(null);

const dynamicContent = {
  onStepChange: (step, tourName) => {
    // Update UI based on the current step
    if (tourName === 'featureTour') {
      switch(step) {
        case 0:
          setHighlightedSection('dashboard');
          break;
        case 1:
          setHighlightedSection('sidebar');
          break;
        case 2:
          setHighlightedSection('settings');
          break;
        default:
          setHighlightedSection(null);
      }
    }
  },
  onComplete: () => {
    // Reset UI when tour ends
    setHighlightedSection(null);
  },
  onSkip: () => {
    // Reset UI when tour is skipped
    setHighlightedSection(null);
  }
};

// Then use it in your NextStep component
<NextStepReact 
  steps={steps}
  {...dynamicContent}
>
  {children}
</NextStepReact>
```

--------------------------------

### Customize Pointer Appearance in Tour Steps

Source: https://nextstepjs.com/docs/react-router/styling

Define `pointerPadding` and `pointerRadius` within individual tour steps to adjust the highlighted area around target elements. Units are in pixels.

```javascript
{
  tour: 'welcome',
  steps: [
    {
      icon: <></>,
      title: 'Welcome',
      content: <></>,
      selector: '#welcome-element',
      side: 'top',
      pointerPadding: 16,    // Padding around the target element (in pixels)
      pointerRadius: 8,      // Border radius of the pointer (in pixels)
    },
    // More steps...
  ],
}
```

--------------------------------

### Basic Localization with Separate Steps Arrays

Source: https://nextstepjs.com/docs/react-router/localization

Define distinct steps arrays for each language (e.g., English and Spanish) and conditionally use the appropriate array based on the current locale. This is suitable for simpler localization needs.

```javascript
// Define steps for different languages
const stepsEn = [
  {
    tour: 'welcome',
    steps: [
      {
        icon: <>👋</>,
        title: 'Welcome',
        content: <>This is the first step</>,
        selector: '#welcome-element',
        side: 'top',
      },
      // More steps...
    ],
  },
];

const stepsEs = [
  {
    tour: 'welcome',
    steps: [
      {
        icon: <>👋</>,
        title: 'Bienvenido',
        content: <>Este es el primer paso</>,
        selector: '#welcome-element',
        side: 'top',
      },
      // More steps...
    ],
  },
];

// Use the appropriate steps array based on locale
const MyApp = ({ locale }) => (
  <NextStepProvider>
    <NextStepReact steps={locale === 'es' ? stepsEs : stepsEn}>
      {/* Your app content */}
    </NextStepReact>
  </NextStepProvider>
);
```

--------------------------------

### Defining Routes in Tour Steps

Source: https://nextstepjs.com/docs/react-router/routing

Add `nextRoute` and `prevRoute` properties to your step objects to specify navigation targets for 'Next' and 'Previous' actions. NextStep will navigate to the specified route before displaying the next or previous step.

```javascript
// In your steps.tsx file
{
  tour: 'routingDemo',
  steps: [
    {
      icon: <>👋</>,
      title: 'Welcome to Page One',
      content: <>This is the first step. Click next to go to page two.</>,
      selector: '#page-one-element',
      side: 'bottom',
      showControls: true,
      showSkip: true,
      // Navigate to page two when clicking "Next"
      nextRoute: '/page-two',
    },
    {
      icon: <>🎉</>,
      title: 'Welcome to Page Two',
      content: <>This is the second step. Click previous to go back to page one.</>,
      selector: '#page-two-element',
      side: 'bottom',
      showControls: true,
      showSkip: true,
      // Navigate back to page one when clicking "Previous"
      prevRoute: '/page-one',
    },
  ],
}
```

--------------------------------

### useNextStep Hook Return Values

Source: https://nextstepjs.com/docs/react/api

The useNextStep hook provides programmatic control over the tour, returning functions to manage the tour's lifecycle and state.

```APIDOC
## useNextStep Hook

The useNextStep hook provides programmatic control over the tour. You can use it to start, stop, skip, or navigate through steps.

### useNextStep Hook Return Values
| Property| Type| Description  
---|---|---
startNextStep| (tourName: string) => void| Starts the specified tour  
closeNextStep| () => void| Stops the current tour  
currentTour| string | null| The name of the current tour  
currentStep| number| The current step index  
setCurrentStep| (step: number, delay?: number) => void| Sets the current step index with optional delay  
isNextStepVisible| boolean| Whether the tour overlay is currently visible
```

--------------------------------

### Step Object Definition

Source: https://nextstepjs.com/docs/react-router/api

Defines the structure for each step within a tour, including content, targeting, and display options.

```APIDOC
## Step Object

### Description
Each step in a tour is defined by a Step object with the following properties:

### Properties
- **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
- **side** ("top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "left-top" | "left-bottom" | "right-top" | "right-bottom") - Optional. Determines where the tooltip should appear relative to the selector
- **showControls** (boolean) - Optional. Determines whether control buttons 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 highlighting the target element
- **pointerRadius** (number) - Optional. The border-radius of the pointer 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 to target. Used with NextStepViewport component.
- **disableInteraction** (boolean) - Optional. If true, prevents any interaction (clicks, hover, etc.) with the highlighted element. Useful for "view-only" tour steps.
```

--------------------------------

### Step Object Properties

Source: https://nextstepjs.com/docs/react/api

Each step in a tour is defined by a Step object, which includes properties for content, targeting, and display options.

```APIDOC
## Step Object

Each step in a tour is defined by a Step object with the following 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  
side| "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "left-top" | "left-bottom" | "right-top" | "right-bottom"| Optional. Determines where the tooltip should appear relative to the selector  
showControls| boolean| Optional. Determines whether control buttons 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 highlighting the target element  
pointerRadius| number| Optional. The border-radius of the pointer 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  
vieportID| string| Optional. The id of the viewport to target. Used with NextStepViewport component.  
disableInteraction| boolean| Optional. If true, prevents any interaction (clicks, hover, etc.) with the highlighted element. Useful for "view-only" tour steps.
```
Tokens:
Raw