### Local Development Setup

Source: https://github.com/baybreezy/nuxt-tour/blob/main/CONTRIBUTING.md

Steps to clone the repository, install dependencies, build the module stub, and start the documentation development server for local testing.

```bash
git clone https://github.com/BayBreezy/nuxt-tour.git
cd nuxt-tour

bun install

bun run dev:prepare

bun run dev
```

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

### Start Docs Development Server Directly

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/README.md

Navigate to the docs directory, install dependencies, and start the docs development server.

```bash
cd docs
bun install
bun run dev
```

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

### Install Dependencies and Build Module

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/README.md

Install dependencies, build the module stub, and start the docs development server from the repository root.

```bash
bun install
bun run dev:prepare
bun run dev
```

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

### Conditionally Start Tour Based on User State

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/api-reference/use-tour-composable.md

This example demonstrates how to conditionally start an onboarding tour only for new users who have not completed it before. It uses `onMounted` to check user state and `isPlayed` to ensure the tour isn't shown again.

```vue
<script setup lang="ts">
import { onMounted } from 'vue'
import { useTour } from '#nuxt-tour/composables'

const user = useUser()
const { isPlayed, start } = useTour('onboarding')

onMounted(async () => {
  // Only show onboarding to new users
  if (!user.value?.hasCompletedOnboarding && !isPlayed.value) {
    await start()
  }
})
</script>
```

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

### Highlight Example with VTour

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/02.examples/highlight.md

This example demonstrates how to use the `VTour` component with the `highlight` and `backdrop` props enabled to visually focus the current target element. The tour automatically starts on page load and can be restarted.

```vue
<template>
  <div class="not-prose">
    <div v-if="isPlayed" class="flex flex-col items-center text-center">
      <p class="mb-5">Click the button below to restart the tour</p>
      <UiButton size="sm" variant="outline" @click="rerunTour"> Restart Tour </UiButton>
    </div>
    <div v-else class="text-center">
      <p class="mb-5">The tour will automatically start when the page loads</p>
    </div>
    <VTour ref="tour" highlight backdrop :name="tourName" :steps="steps" />
  </div>
</template>

<script lang="ts" setup>
  import { VTour } from "#components";
  import type { TourStep } from "#nuxt-tour/types";

  const tourName = "highlight-tour-example";

  const { isPlayed, reset } = useTour(tourName);
  const tour = useTemplateRef<InstanceType<typeof VTour>>("tour");

  const rerunTour = () => reset();

  const steps: TourStep[] = [
    {
      target: "#highlight>a",
      title: "This will be highlighted",
      body: "Setting the highlight prop to true will highlight the target element",
    },
  ];

  onMounted(() => {
    tour.value?.startTour();
  });
</script>
```

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

### Start Docs Dev Server

Source: https://github.com/baybreezy/nuxt-tour/blob/main/CLAUDE.md

Start the documentation development server, which also serves as a playground for manual testing.

```bash
# Start the docs dev server (docs/ is the playground for manual testing)
bun run dev
```

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

### Install Nuxt Tour

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/INDEX.md

Install the nuxt-tour module using npm.

```bash
npm install nuxt-tour
```

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

### CallbacksEmitsExample.vue

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/02.examples/callbacks-emits.md

This example demonstrates how to listen to VTour lifecycle events using Vue's emit system. It displays notifications for tour start, end, skip, and step changes. The tour is automatically started on component mount.

```vue
<template>
  <div class="not-prose">
    <div v-if="isPlayed" class="flex flex-col items-center text-center">
      <p class="mb-5">Click the button below to restart the tour</p>
      <UiButton size="sm" variant="outline" @click="rerunTour"> Restart Tour </UiButton>
    </div>
    <VTour
      ref="tour"
      :name="tourName"
      :steps="steps"
      @tour:start="
        useSonner('Tour started', {
          description: 'The tour has started',
        })
      "
      @tour:end="
        useTimeoutFn(() => {
          useSonner('Tour completed', {
            description: 'The tour has been completed',
          });
        }, 100)
      "
      @tour:skip="
        useTimeoutFn(() => {
          useSonner('Tour skipped', {
            description: 'The tour was skipped',
          });
        }, 100)
      "
      @tour:step-change="
        ({ from, to }) =>
          useSonner(`Step ${from + 1} → ${to + 1}`, {
            description: 'Step changed',
          })
      "
    />
  </div>
</template>

<script lang="ts" setup>
  import { VTour } from "#components";
  import type { TourStep } from "#nuxt-tour/types";

  const tourName = "callbacks-emits-tour-example";

  const { isPlayed, reset } = useTour(tourName);
  const tour = useTemplateRef<InstanceType<typeof VTour>>("tour");

  const rerunTour = () => reset();

  const steps: TourStep[] = [
    {
      target: "#callbacks-and-emits>a",
      title: "Callbacks and Emits",
      body: "A notification fires on every tour event: start, end, skip, and step change.",
    },
    {
      title: "Step change",
      subText: "Watch the notification",
      body: "Moving to this step fired the <strong>tour:step-change</strong> event.",
    },
  ];

  onMounted(() => {
    tour.value?.startTour();
  });
</script>

```

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

### start()

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/api-reference/use-tour-composable.md

Starts the tour from the first step or resumes from a saved step. It respects localStorage completion status and TTL settings, automatically skipping the tour if already played and not expired.

```APIDOC
## start()

### Description
Starts the tour from the first step or resumes from a saved step. It respects localStorage completion status and TTL settings, automatically skipping the tour if already played and not expired.

### Signature
```ts
start(): Promise<void>
```

### Behavior
- If called before the component mounts, sets `_pendingStart = true` and the component picks it up on mount.
- If called after the component mounts, calls the component's `startTour()` directly.
- Respects localStorage completion status and TTL settings.

### Example
```ts
const { start, isPlayed } = useTour("onboarding");
const tourBtn = ref<HTMLElement | null>(null);

onMounted(() => {
  if (!isPlayed.value) {
    await start();
  }
});

// Or via a button:
const replayTour = async () => {
  await reset();  // Clear localStorage
  await start();  // Start fresh
};
```
```

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

### Start Tour Before Component Mount

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/errors.md

Methods like `start()` can be called before the component mounts. They are queued and picked up upon mount. This is the intended pattern for initiating tours early.

```typescript
const { start } = useTour('onboarding')

// Calling before component mounts
await start()  // Sets _pendingStart = true, component picks it up on mount

// Component mounts later
// <VTour name="onboarding" :steps="steps" />
```

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

### Custom Button Configuration Example

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/02.examples/button.md

Demonstrates how to configure custom labels and icons for each tour button (skip, next, previous, finish) using the ButtonConfig object. This example shows a complete Vue component setup for a tour with these custom buttons.

```vue
<template>
  <div class="not-prose">
    <div v-if="isPlayed" class="flex flex-col items-center text-center">
      <p class="mb-5">Click the button below to restart the tour</p>
      <UiButton size="sm" variant="outline" @click="rerunTour"> Restart Tour </UiButton>
    </div>
    <VTour
      ref="tour"
      highlight
      backdrop
      :name="tourName"
      :steps="steps"
      :skip-button="skipBtn"
      :next-button="nextBtn"
      :prev-button="prevBtn"
      :finish-button="finishBtn"
    />
  </div>
</template>

<script lang="ts" setup>
  import { VTour } from "#components";
  import type { ButtonConfig, TourStep } from "#nuxt-tour/types";

  const skipBtn: ButtonConfig = {
    label: "I'm good",
    leftIcon: "heroicons:x-circle",
  };
  const nextBtn: ButtonConfig = {
    label: "Move on",
    rightIcon: "heroicons:arrow-right",
  };
  const prevBtn: ButtonConfig = {
    label: "Go back",
    leftIcon: "heroicons:arrow-left",
  };
  const finishBtn: ButtonConfig = {
    label: "All done",
    rightIcon: "heroicons:check-badge",
  };

  const tourName = "custom-button-tour-example";

  const { isPlayed, reset } = useTour(tourName);
  const tour = useTemplateRef<InstanceType<typeof VTour>>("tour");

  const rerunTour = () => reset();

  const steps: TourStep[] = [
    {
      target: "#custom-buttons>a",
      title: "Different buttons",
      body: "Here we are passing a different configuration to each button.",
    },
    {
      target: "#next-btn-code",
      title: "Next button",
      body: "An icon and a custom label have been passed to the next button.",
    },
    {
      target: "#skip-btn-code",
      title: "Skip button",
      body: "An icon and a custom label have been passed to the skip button.",
    },
    {
      target: "#prev-btn-code",
      title: "Previous button",
      body: "An icon and a custom label have been passed to the previous button.",
    },
    {
      target: "#finish-btn-code",
      title: "Finish button",
      body: "An icon and a custom label have been passed to the finish button.",
    },
  ];

  onMounted(() => {
    tour.value?.startTour();
  });
</script>

<style scoped>
  :deep(#nt-tooltip) {
    max-width: 450px;
  }
  :deep(#nt-action-finish) {
    background-color: var(--color-green-600);
    color: white;
  }
</style>

```

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

### Storage Schema Example

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/configuration.md

Example of the structure for tour state stored in localStorage.

```json
{
  "nt-onboarding": {
    "completed": true,
    "status": "completed",
    "completedAt": "2024-06-24T10:30:00.000Z",
    "lastStep": 4,
    "version": "v1"
  }
}
```

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

### Vue Transition Example

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/02.examples/transition.md

This Vue component demonstrates how to use the `transition` prop with Nuxt Tour. It allows users to select from various transition animations and preview them by starting a tour. The component includes buttons to select transitions, tour steps, and controls to start or reset the tour.

```vue
<template>
  <div class="not-prose flex flex-col gap-5">
    <div>
      <p class="mb-4 text-sm font-medium">Select a transition</p>
      <div class="flex flex-wrap gap-2">
        <button
          v-for="t in transitions"
          :key="t"
          class="rounded-full border px-3 py-1 font-mono text-sm transition-colors"
          :class="
            selected === t
              ? 'border-primary bg-primary/20 text-primary'
              : 'bg-muted text-muted-foreground hover:border-primary'
          "
          @click="selected = t"
        >
          {{ t }}
        </button>
      </div>
    </div>

    <div class="grid grid-cols-3 gap-3">
      <div id="ex-transition-step-a" class="rounded-lg border p-3 text-center">
        <p class="text-xs font-semibold">Step 1</p>
        <p class="text-muted-foreground mt-1 text-xs">First target</p>
      </div>
      <div id="ex-transition-step-b" class="rounded-lg border p-3 text-center">
        <p class="text-xs font-semibold">Step 2</p>
        <p class="text-muted-foreground mt-1 text-xs">Second target</p>
      </div>
      <div id="ex-transition-step-c" class="rounded-lg border p-3 text-center">
        <p class="text-xs font-semibold">Step 3</p>
        <p class="text-muted-foreground mt-1 text-xs">Third target</p>
      </div>
    </div>

    <div class="flex items-center gap-2">
      <UiButton size="sm" variant="outline" :disabled="isActive" @click="start()">
        Start Tour
      </UiButton>
      <UiButton size="sm" variant="ghost" @click="reset()"> Reset </UiButton>
    </div>

    <VTour :name="tourName" :transition="selected" save-to-local-storage="never" :steps="steps" />
  </div>
</template>

<script lang="ts" setup>
  import type { TourStep } from "#nuxt-tour/types";

  const tourName = "transition-tour-example";
  const transitions = ["fade", "slide-up", "slide-down", "slide-left", "slide-right"] as const;
  const selected = ref<(typeof transitions)[number]>("fade");

  const { isActive, start, reset } = useTour(tourName);

  const steps: TourStep[] = [
    {
      target: "#ex-transition-step-a",
      title: "Tooltip transitions",
      body: "Select a transition above and press <strong>Start Tour</strong> to see it in action.",
      popperConfig: { placement: "bottom" },
    },
    {
      target: "#ex-transition-step-b",
      title: "Step change",
      subText: "Watch the animation",
      body: "The same transition plays on every step change — in and out.",
      popperConfig: { placement: "bottom" },
    },
    {
      target: "#ex-transition-step-c",
      title: "Mix and match",
      body: "Reset the tour, pick a different transition, and start again to compare.",
      popperConfig: { placement: "bottom" },
    },
  ];
</script>

```

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

### Install Nuxt Tour with npm or bun

Source: https://github.com/baybreezy/nuxt-tour/blob/main/README.md

Install the nuxt-tour package using either npm or bun package managers.

```bash
# npm
npm install nuxt-tour

# bun
bun add nuxt-tour
```

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

### Start Tour via Template Ref

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/01.getting-started/5.methods.md

Demonstrates starting a tour using a template ref on the VTour component. The `startTour` method is called from a button click event.

```vue
<template>
  <button @click="tour?.startTour()">Start</button>
  <VTour ref="tour" :steps="steps" />
</template>

<script setup lang="ts">
  import { VTour } from "#components";

  const tour = useTemplateRef<InstanceType<typeof VTour>>("tour");
</script>
```

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

### Start Tour

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/api-reference/use-tour-composable.md

Starts the tour from the first step or resumes from a saved step. It respects localStorage completion status and TTL settings. Call before component mount to defer execution.

```typescript
const { start, isPlayed } = useTour("onboarding");
const tourBtn = ref<HTMLElement | null>(null);

onMounted(async () => {
  if (!isPlayed.value) {
    await start();
  }
});

// Or via a button:
const replayTour = async () => {
  await reset();  // Clear localStorage
  await start();  // Start fresh
};
```

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

### Full Nuxt Tour Usage Example

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/api-reference/tour-component.md

A complete Vue.js component demonstrating the integration of the VTour component. It includes step definitions, event handlers for tour lifecycle, and template setup.

```vue
<template>
  <div>
    <h1 class="page-title">Dashboard</h1>
    <button class="action-btn">Get started</button>

    <VTour
      ref="tourRef"
      name="dashboard-tour"
      :steps="steps"
      auto-start
      :highlight="true"
      :backdrop="true"
      @tour:start="onStart"
      @tour:end="onComplete"
      @tour:step-change="onStepChange"
    />
  </div>
</template>

<script setup lang="ts">
import { useTemplateRef } from 'vue'
import type { TourStep } from '#nuxt-tour/types'

const tourRef = useTemplateRef('tourRef')

const steps: TourStep[] = [
  {
    target: '.page-title',
    title: 'Welcome',
    body: 'This is your dashboard. Let us show you around.',
  },
  {
    target: '.action-btn',
    title: 'Get Started',
    body: 'Click here to begin.',
  },
]

const onStart = () => {
  console.log('Tour started')
}

const onComplete = () => {
  console.log('Tour completed')
}

const onStepChange = ({ from, to }) => {
  console.log(`Moved from step ${from} to step ${to}`)
}
</script>
```

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

### Manual Tour Start with Button

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/quick-reference.md

Control tour initiation via a button click. Use `useTemplateRef` to get a reference to the VTour component and call its `startTour` method.

```vue
<script setup>
import { useTemplateRef } from "vue";

const tourRef = useTemplateRef("tour");

const steps = [
  { target: ".feature", title: "Feature", body: "Check this out" },
];

const startTour = async () => {
  await tourRef.value?.startTour();
};
</script>

<template>
  <button @click="startTour">Take a Tour</button>
  <VTour ref="tour" :steps="steps" name="features" />
</template>
```

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

### Composable Tour Example

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/02.examples/composable.md

Demonstrates how to use the `useTour()` composable to control a tour. It displays reactive tour state and provides buttons to start, end, and reset the tour. The tour steps are defined with targets, titles, and bodies, utilizing various elements within the component for interaction.

```vue
<template>
  <div class="not-prose">
    <div class="flex flex-col gap-4">
      <!-- Feature cards the tour will point at -->
      <div class="grid grid-cols-3 gap-3">
        <div id="ex-composable-state" class="bg-muted rounded-lg border p-3 text-center">
          <p class="text-xs font-semibold">Reactive state</p>
          <p class="text-muted-foreground mt-1 text-xs">isActive · currentStep · progress</p>
        </div>
        <div id="ex-composable-controls" class="bg-muted rounded-lg border p-3 text-center">
          <p class="text-xs font-semibold">Controls</p>
          <p class="text-muted-foreground mt-1 text-xs">start · end · skip · reset</p>
        </div>
        <div id="ex-composable-storage" class="bg-muted rounded-lg border p-3 text-center">
          <p class="text-xs font-semibold">Storage helpers</p>
          <p class="text-muted-foreground mt-1 text-xs">markPlayed · markUnplayed</p>
        </div>
      </div>

      <!-- Control buttons -->
      <div class="flex items-center justify-between">
        <div class="flex gap-2">
          <UiButton
            id="ex-composable-start-btn"
            size="sm"
            variant="outline"
            :disabled="isActive"
            @click="start()">
            Start Tour
          </UiButton>
          <UiButton size="sm" variant="outline" :disabled="!isActive" @click="end()">
            End Tour
          </UiButton>
          <UiButton size="sm" variant="outline" :disabled="isActive" @click="reset()">
            Reset
          </UiButton>
        </div>
        <p class="text-muted-foreground text-xs">
          Status:
          <span class="font-medium">
            {{ 
              isActive
                ? `Step ${currentStep + 1} of ${totalSteps}`
                : isPlayed
                  ? "Completed"
                  : "Not started"
            }}
          </span>
        </p>
      </div>
    </div>

    <VTour :name="tourName" :steps="steps" />
  </div>
</template>

<script lang="ts" setup>
  import type { TourStep } from "#nuxt-tour/types";

  const tourName = "composable-tour-example";

  const { isPlayed, isActive, currentStep, totalSteps, start, end, reset } = useTour(tourName);

  const steps: TourStep[] = [
    {
      target: "#ex-composable-start-btn",
      title: "useTour() composable",
      body: "Call <strong>start()</strong> from any component — no template ref required. The composable drives the tour through a shared registry.",
      popperConfig: { placement: "top" },
    },
    {
      target: "#ex-composable-state",
      title: "Reactive state",
      subText: "Always in sync",
      body: "<strong>isActive</strong>, <strong>currentStep</strong>, <strong>totalSteps</strong>, and <strong>progress</strong> update reactively as the tour runs.",
      popperConfig: { placement: "bottom" },
    },
    {
      target: "#ex-composable-controls",
      title: "Controls from anywhere",
      subText: "start · end · skip · next · prev · goTo · pause · resume · reset",
      body: "All methods proxy through the registry so any component can control the same tour, even before <strong>&lt;VTour /&gt;</strong> has mounted.",
      popperConfig: { placement: "bottom" },
    },
    {
      target: "#ex-composable-storage",
      title: "Storage helpers",
      subText: "Work independently of the component",
      body: "<strong>markPlayed()</strong> and <strong>markUnplayed()</strong> read/write localStorage without starting or stopping the tour.",
      popperConfig: { placement: "bottom" },
    },
  ];
</script>

```

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

### Custom Progress Indicator with Slot

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/02.examples/progress.md

This example shows how to use the `#progress` slot to create a fully custom progress indicator for the tour. It displays the current step, total steps, and a visual progress bar. The tour automatically starts on page load.

```vue
<template>
  <div class="not-prose">
    <div v-if="isPlayed" class="flex flex-col items-center text-center">
      <p class="mb-5">Click the button below to restart the tour</p>
      <UiButton size="sm" variant="outline" @click="rerunTour"> Restart Tour </UiButton>
    </div>
    <div v-else class="text-center">
      <p class="mb-5">The tour will automatically start when the page loads</p>
    </div>
    <VTour ref="tour" :name="tourName" :steps="steps" show-progress>
      <template #progress="{ currentStep, totalSteps, progress }">
        <div class="mb-1 flex items-center justify-between text-xs text-zinc-400">
          <span>Step {{ currentStep + 1 }} / {{ totalSteps }}</span>
          <span>{{ Math.round(progress * 100) }}%</span>
        </div>
        <div class="h-1 w-full overflow-hidden rounded-full bg-zinc-100">
          <div
            class="h-full rounded-full bg-sky-500 transition-all duration-300"
            :style="{ width: `${progress * 100}%` }"
          />
        </div>
      </template>
    </VTour>
  </div>
</template>

<script lang="ts" setup>
  import { VTour } from "#components";
  import type { TourStep } from "#nuxt-tour/types";

  const tourName = "progress-tour-example";

  const { isPlayed, reset } = useTour(tourName);
  const tour = useTemplateRef<InstanceType<typeof VTour>>("tour");

  const rerunTour = () => reset();

  const steps: TourStep[] = [
    {
      target: "#progress>a",
      title: "Progress indicator",
      body: "Pass the <strong>show-progress</strong> prop to enable a built-in step counter.",
    },
    {
      title: "Custom progress slot",
      subText: "Full control over the indicator",
      body: "Use the <strong>#progress</strong> slot to render your own indicator — a bar, dots, or anything you like.",
    },
    {
      title: "Slot props",
      body: "The slot receives <strong>currentStep</strong>, <strong>totalSteps</strong>, and <strong>progress</strong> (0–1) so you can drive any UI.",
    },
  ];

  onMounted(() => {
    tour.value?.startTour();
  });
</script>

```

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

### Nuxt Tour: Start Tour Method

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/api-reference/tour-component.md

Use the `startTour` method to programmatically initialize and display the tour. It handles skipping if the tour was previously completed.

```typescript
const tourRef = useTemplateRef("tour");
await tourRef.value?.startTour();
```

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

### Conventional Commit Message Examples

Source: https://github.com/baybreezy/nuxt-tour/blob/main/CONTRIBUTING.md

Examples illustrating the Conventional Commits format for commit messages, including types and scopes.

```bash
feat: add saveToLocalStorage prop
fix: prevent useScrollLock crash in SSR
docs: document useTour composable
chore: bump @vueuse to v14.4.0
```

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

### Custom Styles Example

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/configuration.md

Example of overriding default tour styles using CSS custom properties.

```css
#nt-tooltip {
  --nt-bg: #1e1e2e;
  --nt-text: #cdd6f4;
  /* ... */
}
```

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

### Sequential Tours

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/quick-reference.md

Start tours one after another, ensuring the previous one is completed or played before proceeding. This is useful for guided user flows.

```typescript
const tour1 = useTour("intro");
const tour2 = useTour("basics");

const startSequence = async () => {
  if (!tour1.isPlayed.value) {
    await tour1.start();
    // tour1 emits tour:end when done
  } else if (!tour2.isPlayed.value) {
    await tour2.start();
  }
};
```

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

### next()

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/api-reference/use-tour-composable.md

Moves the tour to the next step. If the tour is not currently running, it will be started first.

```APIDOC
## next()

### Description
Moves the tour to the next step. If the tour is not currently running, it will be started first.

### Signature
```ts
next(): Promise<void>
```

### Example
```ts
const { next } = useTour("onboarding");
const handleKeyDown = (e: KeyboardEvent) => {
  if (e.key === 'ArrowRight') next();
};
```
```

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

### Start Tour via Composable

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/01.getting-started/3.create-tour.md

Control tour playback using the `useTour` composable, allowing you to start, check play status, and reset tours from any component, even before the `<VTour />` component mounts.

```vue
<template>
  <button @click="start()">Start tour</button>
  <VTour name="onboarding" :steps="steps" />
</template>

<script lang="ts" setup>
  const { start, isPlayed, reset } = useTour("onboarding");
</script>
```

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

### Storage Entry After Version Update

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/configuration.md

Example of the localStorage entry after the `storageVersion` has been updated and a tour is replayed.

```json
{
  "nt-onboarding": {
    "completed": true,
    "status": "completed",
    "completedAt": "2024-06-25T14:20:00.000Z",
    "lastStep": 4,
    "version": "v2"
  }
}
```

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

### HTML Element Targeting Example

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/02.examples/html-elements.md

This Vue component demonstrates how to use direct HTMLElement references for tour step targets. It assigns elements in `onMounted` and uses computed properties for tour steps. The tour automatically starts on page load.

```vue
<template>
  <div class="not-prose">
    <div class="flex flex-col gap-4">
      <div class="flex flex-col gap-2 rounded-lg border p-4">
        <p id="htmlToTarget1" class="bg-muted rounded p-2 text-sm">Target element 1</p>
        <p id="htmlToTarget2" class="bg-muted rounded p-2 text-sm">Target element 2</p>
        <p id="htmlToTarget3" class="bg-muted rounded p-2 text-sm">Target element 3</p>
      </div>
      <div v-if="isPlayed" class="flex flex-col items-center text-center">
        <p class="mb-5">Click the button below to restart the tour</p>
        <UiButton size="sm" variant="outline" @click="rerunTour"> Restart Tour </UiButton>
      </div>
      <div v-else class="text-center">
        <p class="mb-5">The tour will automatically start when the page loads</p>
      </div>
    </div>
    <VTour ref="tour" name="html-tour-example" :steps="steps" />
  </div>
</template>

<script lang="ts" setup>
  import { VTour } from "#components";
  import type { TourStep } from "#nuxt-tour/types";

  const tourName = "html-tour-example";

  const { isPlayed, reset } = useTour(tourName);
  const tour = useTemplateRef<InstanceType<typeof VTour>>("tour");

  const htmlTarget1 = ref<HTMLElement | null>(null);
  const htmlTarget2 = ref<HTMLElement | null>(null);
  const htmlTarget3 = ref<HTMLElement | null>(null);

  const rerunTour = () => reset();

  const steps = computed<TourStep[]>(() => [
    {
      target: htmlTarget1.value,
      title: "HTML Elements",
      body: "You can pass an HTMLElement directly as the target.",
    },
    {
      target: htmlTarget2.value,
      title: "HTML Elements",
      body: "This allows for greater flexibility in targeting elements.",
    },
    {
      target: htmlTarget3.value,
      title: "HTML Elements",
      body: "Assign the element in onMounted so the DOM is ready.",
    },
  ]);

  onMounted(() => {
    htmlTarget1.value = document.getElementById("htmlToTarget1");
    htmlTarget2.value = document.getElementById("htmlToTarget2");
    htmlTarget3.value = document.getElementById("htmlToTarget3");
    tour.value?.startTour();
  });
</script>

```

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

### Nuxt Tour: Go To Step Method

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/api-reference/tour-component.md

Jump to a specific step by its zero-based index using `goToStep`. If the tour is not active, it will be started first.

```typescript
await tourRef.value?.goToStep(2);
```

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

### Wait for DOM elements before starting VTour

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/quick-reference.md

Ensure tour elements are rendered before the tour starts, especially when using `auto-start`. Use `start-delay` or handle element rendering asynchronously.

```typescript
// ❌ Tour may start before elements render
<VTour :steps="steps" auto-start />

// ✓ Wait for elements with async steps or delay
<VTour :steps="steps" auto-start :start-delay="200" />
```

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

### Auto-start Tour on Mount

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/01.getting-started/3.create-tour.md

Configure the VTour component to automatically start when the component mounts by using the `auto-start` prop. You can also specify a `start-delay` in milliseconds.

```vue
<template>
  <VTour auto-start :steps="steps" />
</template>
```

```vue
<template>
  <VTour auto-start :start-delay="500" :steps="steps" />
</template>
```

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

### TourStep Usage Examples

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/types.md

Illustrates various ways to define TourStep objects, from minimal configurations to reactive targets, callbacks, custom slots, and Popper.js integration.

```typescript
const steps: TourStep[] = [
  // Minimal step
  {
    target: '.hero',
    title: 'Welcome',
    body: 'This is the hero section',
  },
  
  // Centered step (no target)
  {
    title: 'Important',
    body: 'This message floats in the center',
  },
  
  // Reactive target
  {
    target: computed(() => selectedElement.value ? '#' + selectedElement.value.id : null),
    title: 'Dynamic target',
    body: 'This follows a reactive element',
  },
  
  // With callbacks
  {
    target: '.submit-btn',
    title: 'Submit',
    body: 'Click to submit the form',
    onNext: async () => {
      // Validate form before next step
      if (!await validateForm()) {
        return false  // Abort step transition
      }
    },
    onShow: () => {
      console.log('Step shown!')
    },
  },
  
  // Custom slots
  {
    target: '.card',
    title: 'Cards',
    body: 'Learn about cards',
    slot: 'cards',  // Allows #cards-header, #cards-body slots
  },
  
  // With Popper.js config
  {
    target: '.tooltip-me',
    title: 'Custom placement',
    body: 'This tooltip uses custom Popper config',
    popperConfig: {
      placement: 'left',
      modifiers: [
        { name: 'offset', options: { offset: [0, 20] } },
      ],
    },
  },
]
```

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

### Custom Actions Slot Example

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/01.getting-started/6.slots.md

Replace all action buttons at once using the '#intro-actions' slot. It provides nextStep, prevStep, isLastStep, and endTour functions.

```vue
<template #intro-actions="{ nextStep, prevStep, isLastStep, endTour }">
  <div class="my-actions">
    <button @click="prevStep">Back</button>
    <button v-if="!isLastStep" @click="nextStep">Next</button>
    <button v-else @click="endTour">Finish</button>
  </div>
</template>
```

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

### Configuring Nuxt Tour with TypeScript

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/configuration.md

Example of how to configure Nuxt Tour using TypeScript, ensuring type safety with the `TourOptions` interface. This configuration is then passed to the Nuxt config.

```typescript
import type { TourOptions } from "nuxt-tour";

const config: TourOptions = {
  prefix: "V",
  injectCSS: true,
  storagePrefix: "nt",
  storageVersion: "v1",
};

export default defineNuxtConfig({
  modules: ["nuxt-tour"],
  tour: config,
});
```

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

### Custom Body Slot Example

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/01.getting-started/6.slots.md

Customize the main content area of the tour step using the '#intro-body' slot. It receives the step definition object.

```vue
<template #intro-body="{ step }">
  <div class="my-body" v-html="step.body" />
</template>
```

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

### Example Usage of PopperConfig in TourStep

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/types.md

Demonstrates how to use the popperConfig property within a TourStep to customize the positioning and behavior of tooltips. This allows for fine-grained control over placement and fallback options.

```typescript
const steps: TourStep[] = [
  {
    target: '.element',
    title: 'Custom position',
    popperConfig: {
      placement: 'right',
      modifiers: [
        { name: 'offset', options: { offset: [0, 20] } },
        { name: 'flip', options: { fallbackPlacements: ['left', 'top'] } },
      ],
    },
  },
]
```

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

### Tracking Tour Step Changes with Analytics

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/01.getting-started/7.emits.md

An example of using the `@tour:step-change` event to track user progression through tour steps, sending data to an analytics service.

```vue
<template>
  <VTour :steps="steps" @tour:step-change="track" />
</template>

<script setup lang="ts">
  const track = ({ from, to }: { from: number; to: number }) => {
    analytics.track("tour_step_change", { from, to });
  };
</script>
```

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

### Show Replay Button After Tour Completion

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/api-reference/use-tour-composable.md

This example shows how to display a 'Replay Tour' button only after a tour has been played and is no longer active. It utilizes `isPlayed` and `isActive` states from the composable.

```vue
<template>
  <div>
    <VTour name="onboarding" :steps="steps" />
    <button v-if="isPlayed && !isActive" @click="replay">
      Replay Tour
    </button>
  </div>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import { useTour } from '#nuxt-tour/composables'

const { isPlayed, isActive, reset, start } = useTour('onboarding')

const replay = async () => {
  await reset()
  await start()
}
</script>
```

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

### Build Module Stub

Source: https://github.com/baybreezy/nuxt-tour/blob/main/CLAUDE.md

Run this before anything else after a fresh clone to build the module stub.

```bash
# Build the module stub (run this before anything else after a fresh clone)
bun run dev:prepare
```

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

### Per-Step Transitions Example

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/02.examples/transition.md

Demonstrates how to set individual transition properties for each step in a tour. Steps without a specific transition will fall back to the tour's default or the 'fade' transition.

```vue
<template>
  <div class="not-prose flex flex-col gap-4">
    <div class="grid grid-cols-5 gap-3">
      <div
        v-for="item in stepItems"
        :id="item.id"
        :key="item.id"
        class="bg-muted flex flex-col items-center gap-1 rounded-lg border p-3 text-center"
      >
        <p class="text-xs font-semibold">{{ item.label }}</p>
        <p class="text-muted-foreground font-mono text-[10px]">{{ item.transition }}</p>
      </div>
    </div>

    <div class="flex items-center gap-2">
      <UiButton size="sm" variant="outline" :disabled="isActive" @click="start()">
        Start Tour
      </UiButton>
      <UiButton size="sm" variant="ghost" @click="reset()"> Reset </UiButton>
    </div>

    <VTour :name="tourName" save-to-local-storage="never" :steps="steps" />
  </div>
</template>

<script lang="ts" setup>
  import type { TourStep } from "#nuxt-tour/types";

  const tourName = "transition-per-step-example";
  const { isActive, start, reset } = useTour(tourName);

  const stepItems = [
    { id: "ex-pstep-fade", label: "Step 1", transition: "fade" },
    { id: "ex-pstep-up", label: "Step 2", transition: "slide-up" },
    { id: "ex-pstep-down", label: "Step 3", transition: "slide-down" },
    { id: "ex-pstep-left", label: "Step 4", transition: "slide-left" },
    { id: "ex-pstep-right", label: "Step 5", transition: "slide-right" },
  ] as const;

  const steps: TourStep[] = [
    {
      target: "#ex-pstep-fade",
      title: "fade",
      body: "No <code class='bg-zinc-200! text-zinc-600!'>transition</code> on this step — falls back to the tour default.",
      popperConfig: { placement: "bottom" },
    },
    {
      target: "#ex-pstep-up",
      title: "slide-up",
      body: 'This step sets <code class="bg-zinc-200! text-zinc-600!">transition: "slide-up"</code>.',
      transition: "slide-up",
      popperConfig: { placement: "bottom" },
    },
    {
      target: "#ex-pstep-down",
      title: "slide-down",
      body: 'This step sets <code class="bg-zinc-200! text-zinc-600!">transition: "slide-down"</code>.',
      transition: "slide-down",
      popperConfig: { placement: "bottom" },
    },
    {
      target: "#ex-pstep-left",
      title: "slide-left",
      body: 'This step sets <code class="bg-zinc-200! text-zinc-600!">transition: "slide-left"</code>.',
      transition: "slide-left",
      popperConfig: { placement: "bottom" },
    },
    {
      target: "#ex-pstep-right",
      title: "slide-right",
      body: 'This step sets <code class="bg-zinc-200! text-zinc-600!">transition: "slide-right"</code>.',
      transition: "slide-right",
      popperConfig: { placement: "bottom" },
    },
  ];
</script>
```

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

### Vue Component for Autostart Tour

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/02.examples/autostart.md

This Vue component demonstrates how to use the `auto-start` prop to initiate a tour automatically upon component mount. It includes tour steps and a button to manually restart the tour.

```vue
<template>
  <div>
    <div v-if="isPlayed" class="flex flex-col items-center text-center">
      <p class="mb-5">Click the button below to restart the tour</p>
      <UiButton size="sm" variant="outline" @click="rerunTour"> Restart Tour </UiButton>
    </div>
    <div v-else class="text-center">
      <p class="mb-5">The tour will automatically start when the page loads</p>
    </div>
    <VTour auto-start name="autostart-tour-example" :steps="steps" />
  </div>
</template>

<script lang="ts" setup>
  import type { TourStep } from "#nuxt-tour/types";

  const tourName = "autostart-tour-example";

  const { isPlayed, reset } = useTour(tourName);

  const rerunTour = () => reset();

  const steps: TourStep[] = [
    {
      target: "#autostart>a",
      title: "Autostart",
      subText: "The tour starts automatically when the component mounts",
      body: "Pass the <strong>auto-start</strong> prop to the VTour component and it will begin as soon as it is mounted.",
    },
    {
      title: "No target",
      subText: "Steps without a target are centred on screen",
      body: "If no target is provided (or the selector does not match), the tooltip floats in the middle of the viewport.",
    },
  ];
</script>
```

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

### Create a Tour Popper Instance

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/api-reference/scroll-popper-utilities.md

Initializes a new Popper.js instance for tour tooltips. Call `.update()` to reposition and `.destroy()` to clean up.

```typescript
import { createTourPopper } from '#nuxt-tour/utils/popper'

const tooltip = document.getElementById('nt-tooltip')
const target = document.querySelector('.my-element')

const popperInstance = createTourPopper(target, tooltip)

// Later, update positioning
await popperInstance.update()

// Clean up
popperInstance.destroy()
```

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

### Manage Multiple Tours Simultaneously

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/api-reference/use-tour-composable.md

This example illustrates how to manage multiple independent tours within an application. It shows how to instantiate `useTour` for different tour names and filter them based on their `isPlayed` status.

```vue
<script setup lang="ts">
import { useTour } from '#nuxt-tour/composables'

const onboarding = useTour('onboarding')
const featureHighlight = useTour('feature-highlight')
const advancedTips = useTour('advanced-tips')

const showTourMenu = () => {
  const tours = [
    { name: 'onboarding', label: 'Onboarding', ...onboarding },
    { name: 'featureHighlight', label: 'Feature Highlight', ...featureHighlight },
    { name: 'advancedTips', label: 'Advanced Tips', ...advancedTips },
  ]
  
  // Only show tours that haven't been played yet
  const unplayedTours = tours.filter(t => !t.isPlayed.value)
  
  return unplayedTours
}
</script>
```

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

### Listening to Tour Events

Source: https://github.com/baybreezy/nuxt-tour/blob/main/docs/content/01.getting-started/7.emits.md

Demonstrates how to listen to various tour events such as start, end, skip, and step change using Vue's template syntax and corresponding handler functions in the script.

```vue
<template>
  <VTour
    :steps="steps"
    @tour:start="onStart"
    @tour:end="onEnd"
    @tour:skip="onSkip"
    @tour:step-change="onStepChange"
  />
</template>

<script lang="ts" setup>
  const onStart = () => console.log("Tour started");
  const onEnd = () => console.log("Tour completed");
  const onSkip = () => console.log("Tour skipped");
  const onStepChange = ({ from, to }: { from: number; to: number }) => {
    console.log(`Moved from step ${from} to step ${to}`);
  };
</script>
```

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

### Run All Tests

Source: https://github.com/baybreezy/nuxt-tour/blob/main/CLAUDE.md

Execute all tests for the project.

```bash
# Run all tests
bun run test
```

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

### Unit Test useTour Composable

Source: https://github.com/baybreezy/nuxt-tour/blob/main/_autodocs/quick-reference.md

Write unit tests for the `useTour` composable to verify its functionality, such as starting a tour or tracking its completion status. Note that starting a tour might require a mounted component.

```typescript
import { useTour } from "#nuxt-tour/composables";
import { describe, it, expect } from "vitest";

describe("useTour", () => {
  it("starts a tour", async () => {
    const { isActive, start } = useTour("test");
    expect(isActive.value).toBe(false);
    // await start();  // Note: requires component to be mounted
  });

  it("tracks completion", () => {
    const { isPlayed, markPlayed, markUnplayed } = useTour("test");
    markPlayed();
    expect(isPlayed.value).toBe(true);
    markUnplayed();
    expect(isPlayed.value).toBe(false);
  });
});
```