Tour

Context-aware step-by-step walkthroughs with route sync, target highlights, and custom overlays.

Interactive Demo

Preview tour triggers and test step interactions across routes.

1. Setup Provider in Main Component (App.jsx)

Wrap your routes with `ToursProvider` using React Router's `useLocation` hook for route tracking.

import { BrowserRouter, useLocation, useNavigate } from 'react-router-dom';
import { ToursProvider } from '@bytesui/react';
import { Guides } from './guides';

function AppRoutes({ children }) {
  const location = useLocation();
  const navigate = useNavigate();

  const currentPath = location.pathname + location.search;

  return (
    <ToursProvider
      currentRoutePath={currentPath}
      guides={Guides}
      onNavigate={(path) => navigate(path)}
      onTourComplete={(tourName) => console.log('Tour Complete:', tourName)}
    >
      {children}
    </ToursProvider>
  );
}

2. Render Overlay & Control Tour via Hook

Use `useTour` within child components wrapped by `ToursProvider` to trigger tours and custom completion overlays.

import { useEffect } from 'react';
import { TourOverlay, useTour } from '@bytesui/react';

export default function Page() {
  const tour = useTour();

  useEffect(() => {
    tour.initializeTour('portfolio');
    tour.setCompletionOverlayDuration(5000);
    tour.setCompletionOverlay(
      <div className="celebration-overlay">🎉 Congratulations! Tour Completed.</div>
    );
  }, []);

  return (
    <>
      <div>Page Content</div>
      <TourOverlay />
    </>
  );
}

Overlay Color & Variant

`TourOverlay` is a themed component. Pass `color` (any of the 8 semantic colors) and `variant` (`solid` | `outlined` | `soft` | `plain`) to match the overlay's highlight ring, card background, and action button color to your brand. Defaults to `color="primary"` and `variant="outlined"`.

import { TourOverlay } from '@bytesui/react';

export default function Page() {
  return (
    <>
      <div>Page Content</div>
      <TourOverlay color="secondary" variant="solid" />
    </>
  );
}

Overlay Slot Styling

For deeper customization, pass a `style` prop keyed by `Bui.*` slot names. Slot styles are merged on top of the resolved theme colors and always take precedence.

import { TourOverlay } from '@bytesui/react';

export default function Page() {
  return (
    <>
      <div>Page Content</div>
      <TourOverlay
        color="info"
        variant="soft"
        style={{
          'Bui.cardBox': { borderRadius: '16px', padding: '20px' },
          'Bui.image': { height: '70%' },
          'Bui.actionButton': { fontWeight: 700, textDecoration: 'underline' },
          'Bui.cancelButton': { opacity: 0.6 }
        }}
      />
    </>
  );
}

Default Avatar

ToursProvider's `avatar` prop is optional. If you don't pass one, BytesUI automatically uses a bundled illustrated avatar shipped inside the package — no extra asset setup required. Pass your own image URL or import to override it.

import { ToursProvider } from '@bytesui/react';

// Uses the built-in default avatar automatically
<ToursProvider currentRoutePath={path} guides={Guides}>
  {children}
</ToursProvider>

// Or provide your own avatar image
<ToursProvider currentRoutePath={path} guides={Guides} avatar="/images/guide-avatar.png">
  {children}
</ToursProvider>

3. Guides Schema Definition

Define steps, target CSS selectors, route gates, and navigation actions.

export const Guides = {
  portfolio: {
    name: 'portfolio',
    steps: [
      {
        message: "Hey! Let's build a portfolio that enhances your landing chances.",
        action: '/profile',
        showOnPage: '/',
        showAction: true,
        actionLabel: 'Yes',
        showCancel: true,
        cancelLabel: 'Later',
        modal: true,
        targetSelector: ''
      },
      {
        message: "Please complete required fields and open 'My Account'.",
        showOnPage: '/profile',
        actionLabel: 'Got it',
        showAction: true,
        modal: true,
        targetSelector: "[data-tour-target='tour-navbar-my-account']"
      }
    ]
  }
};

ToursProvider API

Prop	Type	Default	Description
`currentRoutePath`	string	`required`	Active page path used to match step showOnPage routes.
`guides`	Record<string, Guide>	`{}`	Object containing step configurations grouped by tour key.
`avatar`	string	`bundled default avatar`	Avatar image URL or path displayed inside tour speech bubbles. If omitted, BytesUI automatically uses its bundled default illustrated avatar.
`customRouteCompare`	(showOnPage?: string) => boolean	`undefined`	Optional custom matcher used when route comparison differs from a direct pathname equality check.
`onNavigate`	(path: string) => void	`undefined`	Callback triggered when a step requests programmatic route navigation.
`onTourComplete`	(tourName: string) => void	`undefined`	Triggered after user completes the final step of a tour.

useTour Hook Methods

Method	Parameters	Description
`initializeTour`	(tourKey: string) => void	Starts a registered guide from its initial step.
`setCompletionOverlay`	(node: ReactNode) => void	Sets custom JSX element to display upon tour completion.
`setCompletionOverlayDuration`	(ms: number) => void	Defines duration in milliseconds before auto-hiding the completion overlay.

TourOverlay Props

Prop	Type	Default	Description
`color`	'primary' \| 'secondary' \| 'tertiary' \| 'success' \| 'warning' \| 'error' \| 'neutral' \| 'info'	`"primary"`	Semantic color used for the target highlight ring, card background tint, and action button.
`variant`	'solid' \| 'outlined' \| 'soft' \| 'plain'	`"outlined"`	Visual style variant used to resolve the overlay's color tokens.
`style`	TourOverlaySlotStyle	`undefined`	Slot-based style overrides keyed by `Bui.*` slot names. See the slots reference below.

TourOverlay Style Slots

Slot	Description
`Bui.root`	Full-screen overlay/backdrop container.
`Bui.card`	Positioned card wrapper containing the avatar and message box.
`Bui.cardBox`	Message bubble background, padding, and shadow.
`Bui.image`	Avatar `<img>` element.
`Bui.message`	Step message text (`<p>`).
`Bui.actions`	Wrapper around the action and cancel buttons.
`Bui.actionButton`	Primary action button (e.g. 'Next').
`Bui.cancelButton`	Secondary/cancel button (e.g. 'Skip').