Mantine Onboarding Tour

https://gfazioli.github.io/mantine-onboarding-tour
Admin
A Mantine component that enables the creation of onboarding tour effects using overlays, popovers,...
Tokens:14,959
Snippets:77
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Full OnboardingTour implementation example

Source: https://gfazioli.github.io/mantine-onboarding-tour

A complete example demonstrating mixed usage of direct data-onboarding-tour-id attributes and OnboardingTour.Target components.

```tsx
import { OnboardingTour, type OnboardingTourStep } from '@gfazioli/mantine-onboarding-tour';
import { Badge, Button, Divider, Stack } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function AnotherComponent({ open }: { open: () => void }) {
  return (
    <>
      <OnboardingTour.Target id="step-2">
        <Button onClick={open}>Step 2</Button>
      </OnboardingTour.Target>
      <OnboardingTour.Target id="step-3">
        <Button onClick={open}>Step 3</Button>
      </OnboardingTour.Target>
    </>
  );
}

function Demo() {
  const [started, { open, close }] = useDisclosure(false);

  const onboardingSteps: OnboardingTourStep[] = [
    {
      id: 'step-1',
      title: 'Step-1',
      content: <Badge color="lime">I'm a direct child of OnboardingTour</Badge>,
    },
    {
      id: 'step-2',
      title: 'Step-2',
      content: <Badge color="yellow">I'm not a direct child of OnboardingTour</Badge>,
    },
    {
      id: 'step-3',
      title: 'Step-3',
      content: <Badge color="yellow">I'm not a direct child of OnboardingTour</Badge>,
    },
  ];

  return (
    <OnboardingTour
      tour={onboardingSteps}
      started={started}
      onOnboardingTourEnd={close}
      onOnboardingTourSkip={close}
      title="The Title for all steps"
      withSkipButton={false}
      maw={400}
    >
      <Stack justify="center" align="center">
        <Button size="md" radius={256} variant="gradient" onClick={open}>
          👉 Click here to Start the Tour 👈
        </Button>

        <Divider my={32} />
        <Stack w={200} gap={32}>
          <Button data-onboarding-tour-id="step-1" onClick={open}>
            Step 1
          </Button>
          <AnotherComponent open={open} />
        </Stack>
      </Stack>
    </OnboardingTour>
  );
}
```

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

### Install the package

Source: https://gfazioli.github.io/mantine-onboarding-tour

Use either yarn or npm to add the package to your project.

```bash
yarn add @gfazioli/mantine-onboarding-tour
```

```bash
npm install @gfazioli/mantine-onboarding-tour
```

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

### Implement Popover Width Example in Demo.tsx

Source: https://gfazioli.github.io/mantine-onboarding-tour

A complete example demonstrating how to use OnboardingTour.FocusReveal with custom popover content and width settings.

```tsx
import { OnboardingTour } from '@gfazioli/mantine-onboarding-tour';
import { Button, Center, Divider, Stack, Text, Title } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [focused, { close, open }] = useDisclosure(false);

  return (
    <Stack justify="center" align="center">
      <Title order={4}>Popover width example</Title>

      <Center>
        <Button onClick={open}>Reveal the Bottom Card</Button>
      </Center>

      <Divider my={200} label="Divider" />

      <Center>
        <OnboardingTour.FocusReveal
          focused={focused}
          onBlur={close}
          popoverContent={
            <Stack gap="xs">
              <Title order={5}>A step with a lot of content</Title>
              <Text size="sm">
                Without a width ceiling the dropdown grows to fit its content on a single line
                (width: max-content), so wide or non-wrapping content overflows the viewport. The
                default max-width of 400px keeps the popover readable and on-screen.
              </Text>
            </Stack>
          }
          popoverProps={{
            position: 'top',
            // Default max-width is 400px. Uncomment to change it (use 'none' to remove the cap):
            // styles: { dropdown: { maxWidth: 560 } },
          }}
        >
          <Testimonials testimonial={0} />
        </OnboardingTour.FocusReveal>
      </Center>
    </Stack>
  );
}
```

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

### Full Onboarding Tour Implementation

Source: https://gfazioli.github.io/mantine-onboarding-tour

A complete example showing the integration of custom step data, footer rendering, and tour trigger buttons.

```tsx
import { OnboardingTour } from '@gfazioli/mantine-onboarding-tour';
import { Button, Code, Divider, Stack, Text, Title } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [started, { open, close }] = useDisclosure(false);

  const onboardingSteps: OnboardingTourStep<{ price?: number }>[] = [
    {
      id: 'step-1',
      title: 'Step-1',
      content: 'Description of the Step 1',
      price: 12,
    },
    {
      id: 'step-2',
      title: 'Step-2',
      content: 'Description of the Step 2',
    },
    {
      id: 'step-3',
      title: 'Step-3',
      content: 'Description of the Step 3',
      price: 32,
    },
  ];

  return (
    <OnboardingTour
      tour={onboardingSteps}
      started={started}
      onOnboardingTourEnd={close}
      onOnboardingTourSkip={close}
      footer={(onboardingTour: OnboardingTourController) => {
        if (onboardingTour.currentStep?.price) {
          return (
            <Center>
              <Group gap={4}>
                <Text size="xs">Price:</Text>
                <Badge color="orange">${onboardingTour.currentStep?.price}</Badge>
              </Group>
            </Center>
          );
        }
        return (
          <Group grow>
            <Badge color="green">Included in all plans</Badge>
          </Group>
        );
      }}
      maw={400}
    >
      <Stack justify="center" align="center">
        <Button size="md" radius={256} variant="gradient" onClick={open}>
          👉 Click here to Start the Tour 👈
        </Button>

        <Divider my={32} />

        <Stack w={200} gap={32}>
          <Button data-onboarding-tour-id="step-1" onClick={open}>
            Step 1
          </Button>
          <Button data-onboarding-tour-id="step-2" onClick={open}>
            Step 2
          </Button>
          <Button data-onboarding-tour-id="step-3" onClick={open}>
            Step 3
          </Button>
        </Stack>
      </Stack>
    </OnboardingTour>
  );
}
```

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

### Define Onboarding Tour Steps with Custom Cutouts

Source: https://gfazioli.github.io/mantine-onboarding-tour

Example showing how to define step-level overrides for cutout padding and radius to accommodate different element shapes.

```typescript
const steps: OnboardingTourStep[] = [
  {
    id: 'avatar',
    title: 'Your Profile',
    content: 'Click your avatar to open settings.',
    cutoutPadding: 4,
    cutoutRadius: 9999, // circular cutout
  },
  {
    id: 'action-button',
    title: 'Get Started',
    content: 'This uses a pill-shaped cutout.',
    cutoutPadding: 6,
    cutoutRadius: 24,
  },
  {
    id: 'panel',
    title: 'Dashboard',
    content: 'Default rectangular cutout (8px padding, 8px radius).',
    // inherits tour-level defaults
  },
];
```

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

### Implement FocusReveal.Group Demo

Source: https://gfazioli.github.io/mantine-onboarding-tour

Example demonstrating how to wrap multiple FocusReveal components within a Group to apply shared focus effects.

```tsx
import { OnboardingTour } from '@gfazioli/mantine-onboarding-tour';
import { Center, Code, Divider, Stack, Text, Title } from '@mantine/core';

function Demo() {
  return (
    <>
      <Stack justify="center" align="center">
        <Title order={4}>Group Example</Title>

        <Center>
          <Text>
            The <Code>defaultFocused</Code> props is set to <Code>true</Code>, card below is focused
            by default
          </Text>
        </Center>

        <Divider mb={600}
          label={
            <>
              <Text fz={48}>👇</Text>
              <Text>Scroll down</Text>
            </>
          }
        />
      </Stack>

      <OnboardingTour.FocusReveal.Group focusedMode="scale">
        <Stack>
          <Center>
            <OnboardingTour.FocusReveal>
              <Testimonials testimonial={0} />
            </OnboardingTour.FocusReveal>
          </Center>

          <Divider my={200} />

          <Center>
            <OnboardingTour.FocusReveal>
              <Testimonials testimonial={1} />
            </OnboardingTour.FocusReveal>
          </Center>

          <Divider my={200} />

          <Center>
            <OnboardingTour.FocusReveal>
              <Testimonials testimonial={2} />
            </OnboardingTour.FocusReveal>
          </Center>

          <Divider my={200} />
        </Stack>
      </OnboardingTour.FocusReveal.Group>
    </>
  );
}
```

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

### Demonstrating failed target detection

Source: https://gfazioli.github.io/mantine-onboarding-tour

This example shows an attempt to use data-onboarding-tour-id on a component nested inside another, which will fail to register correctly.

```tsx
function AnotherComponent() {
  return (
    <Group>
      {/* ❌ This won't work */}
      <Button data-onboarding-tour-id="my-button">Click me</Button>
      <Button>Cancel</Button>
    </Group>
  );
}

function Demo() {
  const onboardingSteps: OnboardingTourStep[] = [
    {
      id: 'welcome',
      title: 'Welcome to the Onboarding Tour Component',
      content:
        'This is a demo of the Onboarding Tour component, which allows to create onboarding experiences for your users.',
    },
    {
      id: 'my-button',
      title: 'The New Action Button',
      content: 'This is the content for my button',
    },
  ];

  return (
    <OnboardingTour tour={onboardingSteps} started={true}>
      <div>
        <Title data-onboarding-tour-id="welcome">
          Welcome to the Onboarding Tour Component
        </Title>
        <AnotherComponent />
      </div>
    </OnboardingTour>
  );
}
```

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

### Tour Lifecycle Callbacks

Source: https://gfazioli.github.io/mantine-onboarding-tour

Lifecycle callbacks for the OnboardingTour component to handle events like starting, changing steps, completing, or skipping the tour.

```APIDOC
## Tour Lifecycle Callbacks

### Description
Callbacks provided by the OnboardingTour component to track user interaction and tour progress.

### Callbacks
- **onOnboardingTourStart**: Fires when the tour starts.
- **onOnboardingTourChange**: Fires when the active step changes.
- **onOnboardingTourComplete**: Fires when the user finishes the last step.
- **onOnboardingTourSkip**: Fires when the user clicks the skip button.
- **onOnboardingTourEnd**: Fires whenever the tour ends, regardless of completion or skip status.
```

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

### Implement Onboarding Tour with Cutout Highlights

Source: https://gfazioli.github.io/mantine-onboarding-tour

Full component implementation demonstrating the integration of OnboardingTour with various UI elements and custom step configurations.

```tsx
import {
  OnboardingTour,
  type OnboardingTourStep,
} from '@gfazioli/mantine-onboarding-tour';
import { Avatar, Button, Divider, Group, Stack, Text, ThemeIcon } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';
import { IconBell, IconSettings } from '@tabler/icons-react';

function Demo() {
  const [started, { open, close }] = useDisclosure(false);

  const onboardingSteps: OnboardingTourStep[] = [
    {
      id: 'avatar',
      title: 'Your Profile',
      content: 'Click on your avatar to access profile settings.',
      // Circular cutout for round elements
      cutoutPadding: 4,
      cutoutRadius: 9999,
    },
    {
      id: 'settings',
      title: 'Settings',
      content: 'This icon button uses a circular cutout too.',
      cutoutPadding: 4,
      cutoutRadius: 9999,
    },
    {
      id: 'notifications',
      title: 'Notifications',
      content: 'This step uses the default rectangular cutout.',
      // Uses tour-level defaults (cutoutPadding: 8, cutoutRadius: 8)
    },
    {
      id: 'action',
      title: 'Get Started',
      content: 'This button uses a pill-shaped cutout with a larger radius.',
      cutoutPadding: 6,
      cutoutRadius: 24,
    },
  ];

  return (
    <OnboardingTour
      tour={onboardingSteps}
      started={started}
      onOnboardingTourEnd={close}
      onOnboardingTourSkip={close}
      maw={350}
    >
      <Stack justify="center" align="center">
        <Button size="md" radius={256} variant="gradient" onClick={open}>
          Start the Tour
        </Button>

        <Divider my={16} w="100%" />

        <Group justify="center" gap="xl">
          <Avatar
            data-onboarding-tour-id="avatar"
            src="https://raw.githubusercontent.com/mantinedev/mantine/master/.demo/avatars/avatar-1.png"
            radius="xl"
            size="lg"
          />

          <ThemeIcon
            data-onboarding-tour-id="settings"
            variant="light"
            radius="xl"
            size="xl"
          >
            <IconSettings size={24} />
          </ThemeIcon>

          <ThemeIcon
            data-onboarding-tour-id="notifications"
            variant="light"
            size="xl"
          >
            <IconBell size={24} />
          </ThemeIcon>
        </Group>

        <Button data-onboarding-tour-id="action" radius="xl" size="md">
          Get Started
        </Button>
      </Stack>
    </OnboardingTour>
  );
}
```

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

### Cycle through testimonials with FocusReveal

Source: https://gfazioli.github.io/mantine-onboarding-tour

Demonstrates using OnboardingTour.FocusReveal to highlight elements sequentially. Requires @mantine/hooks for hotkey navigation and state to track the active index.

```tsx
import { useState } from 'react';
import { OnboardingTour } from '@gfazioli/mantine-onboarding-tour';
import { Button, Group, Stack, Text, Title } from '@mantine/core';
import { useHotkeys } from '@mantine/hooks';

function Demo() {
  const [focusIndex, setFocusIndex] = useState(-1);
  const MAX_TESTIMONIALS = 3;

  useHotkeys([
    [
      'ArrowRight',
      () =>
        focusIndex >= 0 && setFocusIndex(focusIndex + 1 < MAX_TESTIMONIALS ? focusIndex + 1 : 0),
    ],
    [
      'ArrowLeft',
      () =>
        focusIndex >= 0 &&
        setFocusIndex(focusIndex - 1 >= 0 ? focusIndex - 1 : MAX_TESTIMONIALS - 1),
    ],
  ]);

  return (
    <Stack justify="center" align="center">
      <Title order={1}>Cycle Example</Title>
      <Text fs="italic">Use the arrow keys to cycle through the testimonials</Text>
      <Button onClick={() => setFocusIndex(0)}>Start</Button>

      <Group justify="center">
        {testimonials.map(
          (_, index) =>
            index < MAX_TESTIMONIALS && (
              <OnboardingTour.FocusReveal
                key={`focus-reveal-${index}`}
                focused={focusIndex === index}
                transitionProps={{ duration: 0, exitDuration: 0 }}
                onBlur={() => setFocusIndex(-1)}
                focusedMode="zoom"
              >
                <Testimonials key={`box-${index}`} testimonial={0}>
                  <Group justify="center">
                    <Button
                      size="xs"
                      variant="gradient"
                      onClick={() => setFocusIndex(index + 1 < MAX_TESTIMONIALS ? index + 1 : 0)}
                    >
                      Next
                    </Button>
                  </Group>
                </Testimonials>
              </OnboardingTour.FocusReveal>
            )
        )}
      </Group>
    </Stack>
  );
}
```

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

### Configure OnboardingTour.Target with focusRevealProps

Source: https://gfazioli.github.io/mantine-onboarding-tour

Demonstrates wrapping components with OnboardingTour.Target and applying custom focusRevealProps to control popover positioning and overlay effects.

```tsx
import { OnboardingTour, type OnboardingTourStep } from '@gfazioli/mantine-onboarding-tour';
import { Badge, Button, Divider, Stack } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function AnotherComponent({ open }: { open: () => void }) {
  return (
    <>
      <OnboardingTour.Target
        id="step-2"
        focusRevealProps={{ popoverProps: { position: 'top-end' } }}
      >
        <Button onClick={open}>Step 2</Button>
      </OnboardingTour.Target>
      <OnboardingTour.Target
        id="step-3"
        focusRevealProps={{ popoverProps: { position: 'right-end' }, overlayProps: { blur: 16 } }}
      >
        <Button onClick={open}>Step 3</Button>
      </OnboardingTour.Target>
    </>
  );
}

function Demo() {
  const [started, { open, close }] = useDisclosure(false);

  const onboardingSteps: OnboardingTourStep[] = [
    {
      id: 'step-1',
      title: 'Step-1',
      content: <Badge color="lime">I'm a direct child of OnboardingTour</Badge>,
    },
    {
      id: 'step-2',
      title: 'Step-2',
      content: <Badge color="yellow">I'm not a direct child of OnboardingTour</Badge>,
    },
    {
      id: 'step-3',
      title: 'Step-3',
      content: <Badge color="yellow">I'm not a direct child of OnboardingTour</Badge>,
    },
  ];

  return (
    <OnboardingTour
      tour={onboardingSteps}
      started={started}
      onOnboardingTourEnd={close}
      onOnboardingTourSkip={close}
      title="The Title for all steps"
      withSkipButton={false}
      maw={400}
    >
      <Stack justify="center" align="center">
        <Button size="md" radius={256} variant="gradient" onClick={open}>
          👉 Click here to Start the Tour 👈
        </Button>

        <Divider my={32} />
        <Stack w={200} gap={32}>
          <Button data-onboarding-tour-id="step-1" onClick={open}>
            Step 1
          </Button>
          <AnotherComponent open={open} />
        </Stack>
      </Stack>
    </OnboardingTour>
  );
}
```

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

### Implement OnboardingTour lifecycle callbacks

Source: https://gfazioli.github.io/mantine-onboarding-tour

Use these callbacks to handle specific tour events like completion, skipping, or general termination.

```jsx
<OnboardingTour
  tour={onboardingSteps}
  started={started}
  onOnboardingTourComplete={() => {
    // User finished all steps
    markTourAsCompleted();
  }}
  onOnboardingTourSkip={() => {
    // User dismissed the tour early
    markTourAsSkipped();
  }}
  onOnboardingTourEnd={() => {
    // Always called — close the tour UI
    close();
  }}
>
  {/* Your content */}
</OnboardingTour>
```

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

### Per-Step Responsive Configuration

Source: https://gfazioli.github.io/mantine-onboarding-tour

Demonstrates how to define unique responsive positioning for individual steps using focusRevealProps.

```typescript
const steps: OnboardingTourStep[] = [
  {
    id: 'step1',
    title: 'Bottom on mobile, right on desktop',
    content: 'Position adapts to screen size',
    focusRevealProps: {
      popoverProps: {
        position: { base: 'bottom', sm: 'right' },
        offset: { base: 8, sm: -4 },
      },
    },
  },
  {
    id: 'step2',
    title: 'Top on mobile, left on large screens',
    content: 'Different breakpoints per step',
    focusRevealProps: {
      popoverProps: {
        position: { base: 'top', lg: 'left' },
        width: { base: 'target', md: 350 },
      },
    },
  },
];
```

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

### OnboardingTour.FocusReveal.Group

Source: https://gfazioli.github.io/mantine-onboarding-tour

The OnboardingTour.FocusReveal.Group component allows you to highlight multiple components at the same time and control multiple OnboardingTour.FocusReveal components simultaneously.

```APIDOC
## OnboardingTour.FocusReveal.Group

### Description
This component allows you to highlight multiple components at the same time and control multiple `OnboardingTour.FocusReveal` components simultaneously by setting common properties.

### Props
- **focusedMode** (OnboardingTourFocusRevealFocusedMode) - Optional - FocusReveal mode/effects when focused.
- **withReveal** (boolean) - Optional - Indicator if element should be revealed. Default `false`.
- **withOverlay** (boolean) - Optional - Will render overlay if set to `true`.
- **overlayProps** (OverlayProps & ElementProps<'div'>) - Optional - Props passed down to `Overlay` component.
- **transitionProps** (TransitionOverride) - Optional - Props passed down to the `Transition` component used to animate the Overlay.
- **children** (React.ReactNode) - Optional - Content to be wrapped by the group.
```

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

### Define Onboarding Tour Steps

Source: https://gfazioli.github.io/mantine-onboarding-tour

Structure an array of OnboardingTourStep objects to define tour steps, supporting both static strings and dynamic components for titles and content.

```typescript
const onboardingSteps: OnboardingTourStep[] = [
  {
    id: 'welcome',
    // Simple string
    title: 'Welcome to the Onboarding Tour Component',
    // Component
    content: <Text size="lg">Hello world!</Text>,
  },
  {
    id: 'subtitle',
    title: 'Another title',
    content: (tourController: OnboardingTourController) => (
      <Text size="lg">
        Hello world! {tourController.currentStep.id}
      </Text>
    ),
  },
];
```

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

### OnboardingTourController

Source: https://gfazioli.github.io/mantine-onboarding-tour

The OnboardingTourController interface provides methods to programmatically control the tour state, including navigation and termination.

```APIDOC
## OnboardingTourController

### Description
Interface for managing the state and navigation of an onboarding tour.

### Methods
- **setCurrentStepIndex(index: number)**: Sets the current tour step by index.
- **startTour()**: Starts the tour.
- **endTour()**: Ends the tour programmatically.
- **skipTour()**: Skips the tour (user dismissed).
- **nextStep()**: Advances to the next tour step.
- **prevStep()**: Returns to the previous tour step.
```

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

### Implement Multiple Components Onboarding Tour

Source: https://gfazioli.github.io/mantine-onboarding-tour

Uses React state and Mantine hooks to manage focus index and keyboard navigation across multiple testimonial components.

```tsx
import { useState } from 'react';
import { OnboardingTour } from '@gfazioli/mantine-onboarding-tour';
import { Button, Group, Paper, Stack, Text, Title } from '@mantine/core';
import { useHotkeys } from '@mantine/hooks';

function Demo() {
  const [focusIndex, setFocusIndex] = useState(-1);
  const MAX_TESTIMONIALS = 3;

  useHotkeys([
    [
      'ArrowRight',
      () =>
        focusIndex >= 0 && setFocusIndex(focusIndex + 1 < MAX_TESTIMONIALS ? focusIndex + 1 : 0),
    ],
    [
      'ArrowLeft',
      () =>
        focusIndex >= 0 &&
        setFocusIndex(focusIndex - 1 >= 0 ? focusIndex - 1 : MAX_TESTIMONIALS - 1),
    ],
  ]);

  const descriptions = [
    'This is the first description.',
    'This is the second description.',
    'This is the third description.',
    'This is the fourth description.',
  ];

  return (
    <Stack justify="center" align="center">
      <Title order={1}>Multiple components Example</Title>
      <Text fs="italic">Use the arrow keys to cycle through the testimonials</Text>
      <Button onClick={() => setFocusIndex(0)}>Start</Button>

      <Group justify="center">
        {testimonials.map(
          (_, index) =>
            index < MAX_TESTIMONIALS && (
              <OnboardingTour.FocusReveal
                key={`focus-reveal-${index}`}
                focused={focusIndex === index}
                transitionProps={{ duration: 0, exitDuration: 0 }}
                onBlur={() => setFocusIndex(-1)}
                focusedMode="zoom"
              >
                <Testimonials key={`box-${index}`} testimonial={0}>
                  <Group justify="center">
                    <Button
                      size="xs"
                      variant="gradient"
                      onClick={() => setFocusIndex(index + 1 < MAX_TESTIMONIALS ? index + 1 : 0)}
                    >
                      Next
                    </Button>
                  </Group>
                </Testimonials>
              </OnboardingTour.FocusReveal>
            )
        )}
      </Group>
      {focusIndex >= 0 && (
        <OnboardingTour.FocusReveal defaultFocused={true} withReveal={false}>
          <Paper withBorder shadow="sm" p={16} mt={32}>
            <Group>
              <Text>{descriptions[focusIndex]}</Text>
              <Button size="xs" onClick={() => setFocusIndex(-1)}>
                Stop
              </Button>
            </Group>
          </Paper>
        </OnboardingTour.FocusReveal>
      )}
    </Stack>
  );
}
```

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

### OnboardingTour Component

Source: https://gfazioli.github.io/mantine-onboarding-tour

The main component used to wrap the application or section where the onboarding tour will be displayed.

```APIDOC
## OnboardingTour

### Description
Wraps the application content to provide an onboarding tour experience. It manages the tour state and step configuration.

### Props
- **tour** (OnboardingTourStep[]) - Required - Array of step objects defining the tour sequence.
- **started** (boolean) - Required - Controls whether the tour is currently active.
- **onOnboardingTourEnd** (function) - Optional - Callback triggered when the tour finishes.
- **onOnboardingTourSkip** (function) - Optional - Callback triggered when the tour is skipped.
- **maw** (number) - Optional - Maximum width of the tour popover.

### OnboardingTourStep Object
- **id** (string) - Required - Unique identifier matching the `data-onboarding-tour-id` attribute on the target element.
- **title** (string) - Required - Title of the tour step.
- **content** (string) - Required - Body text for the tour step.
- **cutoutPadding** (number) - Optional - Padding around the cutout highlight (default: 8).
- **cutoutRadius** (number) - Optional - Border radius of the cutout (default: 8).
```

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

### Implement OnboardingTour Component

Source: https://gfazioli.github.io/mantine-onboarding-tour

Defines an array of tour steps and wraps application content with the OnboardingTour component to manage tour state and custom rendering.

```tsx
import { OnboardingTour } from '@gfazioli/mantine-onboarding-tour';
import { Button, Code, Divider, Stack, Text, Title } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [started, { open, close }] = useDisclosure(false);

  const onboardingSteps: OnboardingTourStep[] = [
    {
      id: 'step-1',
      title: 'Step-1',
      content: 'Content of the Step 1',
    },
    {
      id: 'step-2',
      title: 'Step-2',
      content: 'Content of the Step 2',
    },
    {
      id: 'step-3',
      title: 'Step-3',
      content: 'Content of the Step 3',
    },
  ];

  return (
    <OnboardingTour
      tour={onboardingSteps}
      focusRevealProps={{
        popoverProps: {
          position: 'top',
        },
      }}
      started={started}
      onOnboardingTourEnd={close}
      onOnboardingTourSkip={close}
      title={(tourController: OnboardingTourController) => (
        <Title c="blue" order={4}>
          {tourController.currentStep?.title as string}
        </Title>
      )}
      content={(tourController: OnboardingTourController) => (
        <Text c="lime" size="lg">
          {tourController.currentStep?.content as string}
        </Text>
      )}
      maw={400}
    >
      <Stack justify="center" align="center">
        <Button size="md" radius={256} variant="gradient" onClick={open}>
          👉 Click here to Start the Tour 👈
        </Button>

        <Divider my={32} />

        <Group>
          <Button data-onboarding-tour-id="step-1" onClick={open}>
            Step 1
          </Button>
          <Button data-onboarding-tour-id="step-2" onClick={open}>
            Step 2
          </Button>
          <Button data-onboarding-tour-id="step-3" onClick={open}>
            Step 3
          </Button>
        </Group>
      </Stack>
    </OnboardingTour>
  );
}
```

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

### Implementing OnboardingTour.Target for nested components

Source: https://gfazioli.github.io/mantine-onboarding-tour

Wrapping a component with OnboardingTour.Target ensures the tour correctly identifies the target element even when nested.

```tsx
function AnotherComponent() {
  return (
    <Group>
      {/* ✅ This will work */}
      <OnboardingTour.Target id="my-button">
        <Button>Click me</Button>
      </OnboardingTour.Target>
      <Button>Cancel</Button>
    </Group>
  );
}

function Demo() {
  const onboardingSteps: OnboardingTourStep[] = [
    {
      id: 'welcome',
      title: 'Welcome to the Onboarding Tour Component',
      content:
        'This is a demo of the Onboarding Tour component, which allows to create onboarding experiences for your users.',
    },
    {
      id: 'my-button',
      title: 'The New Action Button',
      content: 'This is the content for my button',
    },
  ];

  return (
    <OnboardingTour tour={onboardingSteps} started={true}>
      <div>
        <Title data-onboarding-tour-id="welcome">
          Welcome to the Onboarding Tour Component
        </Title>
        <AnotherComponent />
      </div>
    </OnboardingTour>
  );
}
```

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

### Define Custom Step Properties

Source: https://gfazioli.github.io/mantine-onboarding-tour

Extend the onboarding steps with custom fields like price to store additional metadata for each tour step.

```typescript
const onboardingSteps: OnboardingTourStep[] = [
  {
    id: 'step-2',
    title: 'Step-2',
    description: 'Description of the Step 2',
    price: 12,
  },
];
```

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

### Implement Onboarding Tour component

Source: https://gfazioli.github.io/mantine-onboarding-tour

Define tour steps and wrap your content with the OnboardingTour component, using data-onboarding-tour-id attributes to identify target elements.

```tsx
import { OnboardingTour } from '@gfazioli/mantine-onboarding-tour';
import { Button, Center, Code, Divider, Group, Stack, Text, Title } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';
function Demo() {
const [started, { open, close }] = useDisclosure(false);

  const onboardingSteps: OnboardingTourStep[] = [
    {
      id: 'welcome',
      title: 'Welcome to the Onboarding Tour Component',
      content:
        'This is a demo of the Onboarding Tour component, which allows to create onboarding experiences for your users.',
    },
    {
      id: 'subtitle',
      title: 'Subtitle',
      content: (
        <Text>
          You can select any component by using the <Code>data-onboarding-tour-id</Code> attribute
        </Text>
      ),
    },
    {
      id: 'button-see-all',
      title: 'New Features',
      content: 'Now you can click on the button "See all" to display all the testimonials',
    },
    {
      id: 'testimonial-2',
      title: 'New Testimonial Layout',
      content: 'We have improved the Testimonial layout',
    },
  ];

  return (
    <OnboardingTour
      tour={onboardingSteps}
      started={started}
      onOnboardingTourEnd={close}
      onOnboardingTourSkip={close}
      maw={400}
      header={(tourController: OnboardingTourController) => (
        <Image
          mah={150}
          radius="md"
          src={`https://raw.githubusercontent.com/mantinedev/mantine/master/.demo/images/bg-${tourController.currentStepIndex + 1}.png`}
        />
      )}

    >
      <Stack justify="center" align="center">
        <Title data-onboarding-tour-id="welcome" order={4}>
          A simple example of the Onboarding Tour component
        </Title>
        <Text data-onboarding-tour-id="subtitle">👉 New amazing Mantine extension component</Text>

        <Center>
          <Button data-onboarding-tour-id="button-see-all">
            See all testimonials
          </Button>
        </Center>

        <Group justify="center">
          <Testimonials testimonial={0} />
          <Testimonials data-onboarding-tour-id="testimonial-2" testimonial={1} />
        </Group>
      </Stack>
    </OnboardingTour>
  );
}
```

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

### Implement Uncontrolled OnboardingTour

Source: https://gfazioli.github.io/mantine-onboarding-tour

Uses the defaultFocused prop to automatically highlight children without manual state management.

```tsx
import { OnboardingTour } from '@gfazioli/mantine-onboarding-tour';
import { Center, Code, Divider, Stack, Text, Title } from '@mantine/core';

function Demo() {

  return (
    <Stack justify="center" align="center">
      <Title order={4}>Simple (uncontrolled) Example</Title>

      <Center>
        <Text>
          The <Code>defaultFocused</Code> props is set to <Code>true</Code>, card below is focused
          by default
        </Text>
      </Center>

      <Divider mb={600}
        label={
          <>
            <Text fz={48}>👇</Text>
            <Text>Scroll down</Text>
          </>
        }
      />

      <Center>
        <OnboardingTour.FocusReveal defaultFocused={true} withReveal={false}>
          <Testimonials testimonial={0} />
        </OnboardingTour.FocusReveal>
      </Center>

      <Divider my={200} />
    </Stack>
  );
}
```

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

### Implement a Custom Stepper with OnboardingTour

Source: https://gfazioli.github.io/mantine-onboarding-tour

Demonstrates using the stepper prop to replace the default Mantine Stepper with a custom Rating component controlled by the OnboardingTourController.

```tsx
import { FocusRevealProps } from '@gfazioli/mantine-focus-reveal';
import {
  OnboardingTour,
  OnboardingTourController,
  type OnboardingTourStep,
} from '@gfazioli/mantine-onboarding-tour';
import { Badge, Button, Center, Divider, Group, Rating, Stack } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [started, { open, close }] = useDisclosure(false);

  const focusRevealProps: FocusRevealProps = {
    popoverProps: {
      position: 'top',
    },
  };

  const onboardingSteps: OnboardingTourStep[] = [
    {
      id: 'step-1',
      title: 'Step-1',
      content: 'Content of the Step 1',
    },
    {
      id: 'step-2',
      title: 'Step-2',
      content: 'Content of the Step 2',
      freeTrialBadge: (
        <Center>
          <Badge color="lime">Free trial available</Badge>
        </Center>
      ),
    },
    {
      id: 'step-3',
      title: 'Step-3',
      content: 'Content of the Step 3',
    },
  ];

  const customStepper = (tourController: OnboardingTourController) => (
    <Center>
      <Rating
        count={tourController.tour.length}
        value={(tourController.currentStepIndex ?? 0) + 1}
        onChange={(value) => tourController.setCurrentStepIndex(value - 1)}
      />
    </Center>
  );

  return (
    <OnboardingTour
      tour={onboardingSteps}
      focusRevealProps={focusRevealProps}
      started={started}
      onOnboardingTourEnd={close}
      onOnboardingTourSkip={close}
      stepper={customStepper}
      maw={400}
    >
      <Stack justify="center" align="center">
        <Button size="md" radius={256} variant="gradient" onClick={open}>
          👉 Click here to Start the Tour 👈
        </Button>

        <Divider my={32} />

        <Group>
          <Button data-onboarding-tour-id="step-1" onClick={open}>
            Step 1
          </Button>
          <Button data-onboarding-tour-id="step-2" onClick={open}>
            Step 2
          </Button>
          <Button data-onboarding-tour-id="step-3" onClick={open}>
            Step 3
          </Button>
        </Group>
      </Stack>
    </OnboardingTour>
  );
}
```

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

### Implement Onboarding Tour Component

Source: https://gfazioli.github.io/mantine-onboarding-tour

Integrate the OnboardingTour component into a React application, utilizing data-onboarding-tour-id attributes on target elements to trigger specific steps.

```tsx
import { OnboardingTour } from '@gfazioli/mantine-onboarding-tour';
import { Button, Code, Divider, Stack, Text, Title } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [started, { open, close }] = useDisclosure(false);

  const onboardingSteps: OnboardingTourStep[] = [
    {
      id: 'step-1',
      title: (
        <Title order={4} c="lime">
          Title in a <Code>Title</Code> component
        </Title>
      ),
      content: (
        <Text c="red">
          Description in a <Code>Text</Code> component with color red
        </Text>
      ),
    },
    {
      id: 'step-2',
      title: 'Simple Title String',
      content: (tourController: OnboardingTourController) => (
        <Text>
          Description by using the function <Code>(tourController: OnboardingTourController)</Code> so we can get some more information such as the step: {tourController.currentStepIndex}
        </Text>
      ),
    },
    {
      id: 'step-3',
      content: <LoginForm />,
    },
  ];

  return (
    <OnboardingTour
      tour={onboardingSteps}
      started={started}
      onOnboardingTourEnd={close}
      onOnboardingTourSkip={close}
      maw={400}
    >
      <Stack justify="center" align="center">
        <Button size="md" radius={256} variant="gradient" onClick={open}>
          👉 Click here to Start the Tour 👈
        </Button>

        <Divider my={32} />

        <Stack w={200} gap={32}>
          <Button data-onboarding-tour-id="step-1" onClick={open}>
            Title
          </Button>
          <Button data-onboarding-tour-id="step-2" onClick={open}>
            Description
          </Button>
          <Button data-onboarding-tour-id="step-3" onClick={open}>
            Content
          </Button>
        </Stack>
      </Stack>
    </OnboardingTour>
  );
}
```

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

### Define OnboardingTourController interface

Source: https://gfazioli.github.io/mantine-onboarding-tour

The OnboardingTourController interface defines the state and available actions for managing a tour.

```typescript
export type OnboardingTourController = Readonly<{
  /** List of tour steps */
  tour: OnboardingTourStep[];

  /** Current step */
  currentStep: OnboardingTourStep | undefined;

  /** Current step index of the tour. Zero-based index */
  currentStepIndex: number | undefined;

  /** ID of the selected tour */
  selectedStepId: string | undefined;

  /** Set the current index */
  setCurrentStepIndex: (index: number) => void;

  /** Start the tour */
  startTour: () => void;

  /** End the tour programmatically */
  endTour: () => void;

  /** Skip the tour (user dismissed) */
  skipTour: () => void;

  /** Go to the next tour */
  nextStep: () => void;

  /** Go to the previous tour */
  prevStep: () => void;

  /** Options of the tour */
  options: OnboardingTourOptions;
}>;
```

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

### Configure Global Tour Props

Source: https://gfazioli.github.io/mantine-onboarding-tour

Apply global configuration props like title directly to the OnboardingTour component, which overrides individual step settings.

```tsx
import { OnboardingTour } from '@gfazioli/mantine-onboarding-tour';
import { Button, Code, Divider, Stack, Text, Title } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [started, { open, close }] = useDisclosure(false);

  const onboardingSteps: OnboardingTourStep[] = [
    {
      id: 'step-1',
      title: 'Step-1',
      content: 'Content of the Step 1',
    },
    {
      id: 'step-2',
      title: 'Step-2',
      content: 'Content of the Step 2',
      myCustomInfo: <Badge>Free trial available</Badge>,
    },
    {
      id: 'step-3',
      title: 'Step-3',
      content: 'Content of the Step 3',
    },
  ];

  return (
    <OnboardingTour
      tour={onboardingSteps}
      started={started}
      onOnboardingTourEnd={close}
      onOnboardingTourSkip={close}
      title="The Title for all steps"
      maw={400}
    >
      <Stack justify="center" align="center">
        <Button size="md" radius={256} variant="gradient" onClick={open}>
          👉 Click here to Start the Tour 👈
        </Button>

        <Divider my={32} />

        <Stack w={200} gap={32}>
          <Button data-onboarding-tour-id="step-1" onClick={open}>
            Step 1
          </Button>
          <Button data-onboarding-tour-id="step-2" onClick={open}>
            Step 2
          </Button>
          <Button data-onboarding-tour-id="step-3" onClick={open}>
            Step 3
          </Button>
        </Stack>
      </Stack>
    </OnboardingTour>
  );
}
```

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

### Implement Focus Reveal Component

Source: https://gfazioli.github.io/mantine-onboarding-tour

Demonstrates basic usage of the FocusReveal component to highlight a target element, controlled by the focused state.

```tsx
import { OnboardingTour, type OnboardingTourFocusRevealProps} from '@gfazioli/mantine-onboarding-tour';
import { Button, Center, Divider, Group, Stack, Text, Title } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [focused, { close, open }] = useDisclosure(false);

  return (
    <Stack justify="center" align="center">
      <Title order={4}>A simple example of the Focus Reveal component</Title>
      <Text>👉 Scroll up the page to remove the focus</Text>

      <Center>
        <Button onClick={open}>Set the Focus to the below component</Button>
      </Center>

      <Divider my={256} />

      <Group justify="center">
        <Testimonials testimonial={0} />
        <OnboardingTour.FocusReveal focused={focused}  onBlur={close}>
          <Testimonials testimonial={1} />
        </OnboardingTour.FocusReveal>
      </Group>
    </Stack>
  );
}
```

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

### Import package styles

Source: https://gfazioli.github.io/mantine-onboarding-tour

Include the required CSS at the root of your application or within a CSS layer.

```css
import '@gfazioli/mantine-onboarding-tour/styles.css';
```

```css
import '@gfazioli/mantine-onboarding-tour/styles.layer.css';
```

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

### Default Popover Configuration

Source: https://gfazioli.github.io/mantine-onboarding-tour

Shows the default responsive popover settings used by the component.

```javascript
// Default popover props (you don't need to set these explicitly)
popoverProps: {
  position: { base: 'bottom', sm: 'left' },
  withArrow: true,
  arrowSize: 16,
  offset: -4,
  middlewares: { shift: { padding: 20 }, flip: true },
  preventPositionChangeWhenVisible: false,
}
// The dropdown is additionally capped at `max-width: 400px` by default (see "Popover width").
```
Tokens:
Raw