### Install VueJS Tour

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Install the package using npm, pnpm, yarn, or bun.

```sh
npm add @globalhive/vuejs-tour
# or
pnpm add @globalhive/vuejs-tour
# or
yarn add @globalhive/vuejs-tour
# or
bun add @globalhive/vuejs-tour
```

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

### VTour Component with Highlight Enabled

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/highlight-target.md

This example demonstrates a complete setup for the `VTour` component, including enabling the `highlight` prop, auto-starting the tour, and disabling local storage saving.

```vue
<script setup>
import VTour from '../../src/components/VTour.vue';
import "../../src/style/style.scss";

const steps = [{ target: '[data-step="0"]', content: 'Target highlighted' }];

</script>
<VTour :steps="steps" autoStart saveToLocalStorage='never' noScroll highlight/>

<div class="custom-block example">
    <p data-step="0">Target</p>
</div>
```

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

### startTour()

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Programmatically start the tour from the first step or the last saved step. Useful for event-driven tour starts.

```APIDOC
## `startTour()` — Start the Tour

Programmatically start the tour from the first step (or the last saved step when `saveToLocalStorage="step"`). Use `autoStart` prop for mount-time start, or call `startTour()` via template ref for event-driven starts.

### Method Signature

`tour.value?.startTour()`

### Usage Example

```vue
<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { VTour } from '@globalhive/vuejs-tour';
import type { ITourStep } from '@globalhive/vuejs-tour';

const tour = ref<InstanceType<typeof VTour>>();

const steps: ITourStep[] = [
  { target: '#feature-a', content: 'This is Feature A' },
  { target: '#feature-b', content: 'This is Feature B' },
];

// Start tour 2 seconds after mount
onMounted(() => {
  setTimeout(() => {
    tour.value?.startTour();
  }, 2000);
});
</script>

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

  <div id="feature-a">Feature A</div>
  <div id="feature-b">Feature B</div>
</template>
```
```

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

### VTour with Backdrop Enabled via Script Setup

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/using-a-backdrop.md

This example demonstrates how to use the `VTour` component with the backdrop enabled, triggered by a button click. Ensure the necessary imports and styles are included.

```vue
<script setup>
import { ref } from 'vue';
import VTour from '../../src/components/VTour.vue';
import "../../src/style/style.scss";

const vTourComponent = ref();
const steps = [{ target: '[data-step="0"]', content: 'Click "Done" to close the Tooltip' }];

function clickToStart() {
    vTourComponent.value.startTour();
}
</script>

<VTour ref="vTourComponent" :steps="steps" saveToLocalStorage='never' noScroll backdrop/>

<div class="custom-block example">
    <button data-step="0" @click="clickToStart">Click To Start<br>With Backdrop Enabled</button>
</div>
```

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

### Start VTour Programmatically

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Initiate the tour from the first step or the last saved step using the startTour() method. This is useful for event-driven tour starts.

```vue
<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { VTour } from '@globalhive/vuejs-tour';
import type { ITourStep } from '@globalhive/vuejs-tour';

const tour = ref<InstanceType<typeof VTour>>();

const steps: ITourStep[] = [
  { target: '#feature-a', content: 'This is Feature A' },
  { target: '#feature-b', content: 'This is Feature B' },
];

// Start tour 2 seconds after mount
onMounted(() => {
  setTimeout(() => {
    tour.value?.startTour();
  }, 2000);
});
</script>

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

  <div id="feature-a">Feature A</div>
  <div id="feature-b">Feature B</div>
</template>

```

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

### Basic VueJS Tour Setup

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/getting-started.md

Import and use the VTour component and its default styles in your App.vue file. Ensure you have Vue 3.x or higher installed.

```vue
<script setup lang='ts'>
    import HelloWorld from './components/HelloWorld.vue';
    import { VTour } from '@globalhive/vuejs-tour';
    import '@globalhive/vuejs-tour/dist/style.css';
</script>

<template>
    <VTour/>
    <div>
        <a href="https://vitejs.dev" target="_blank">
            <img src="/vite.svg" class="logo" alt="Vite logo" />
        </a>
        <a href="https://vuejs.org/" target="_blank">
            <img src="./assets/vue.svg" class="logo vue" alt="Vue logo" />
        </a>
    </div>
    <HelloWorld msg="Vite + Vue" />
</template>
```

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

### Install VueJS Tour with npm

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/getting-started.md

Use npm to add VueJS Tour to your project dependencies.

```sh
npm add @globalhive/vuejs-tour
```

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

### Install VueJS Tour with bun

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/getting-started.md

Use bun to add VueJS Tour to your project dependencies.

```sh
bun add @globalhive/vuejs-tour
```

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

### Install VueJS Tour with pnpm

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/getting-started.md

Use pnpm to add VueJS Tour to your project dependencies.

```sh
pnpm add @globalhive/vuejs-tour
```

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

### Setting Step Placement

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/using-placement.md

Example of setting the `placement` property for a tour step to 'top'. The tour will attempt to place it at the top-middle.

```vue
<script setup>
  const steps = [{
    target: '[data-step=0]',
    content: 'Top Placement',
    placement: 'top' // Placed at top-middle if enough space // [!code ++]
  }];
</script>
```

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

### Automatically Start Tour in Vue.js

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/create-a-tour.md

Use the `autoStart` prop on the VTour component to automatically initiate the tour when the component is mounted.

```vue
<template>
    <VTour :steps="steps" autoStart/>
    <div>
        <a href="https://vitejs.dev" target="_blank">
            <img src="/vite.svg" class="logo" alt="Vite logo" />
        </a>
        <a href="https://vuejs.org/" target="_blank">
            <img src="./assets/vue.svg" class="logo vue" alt="Vue logo" />
        </a>
    </div>
    <HelloWorld msg="Vite + Vue" />
</template>
```

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

### Manually Start Tour with `ref`

Source: https://github.com/globalhive/vuejs-tour/blob/master/README.md

Control tour initiation programmatically by using a `ref` to access the component instance and calling the `startTour()` method within `onMounted`.

```vue
<template>
  <div>
    <div id="selectByID">Selected by its id 'selectByID'</div>
    <p class="selectByClass">Telected by its class 'selectByClass'</p>
    <button data-step="3">Selected by the 'data-step="3"' attribute</button>

    <VTour ref="tour" :steps="steps"/>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';
const tour = ref(null);

const steps = [...];

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

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

### Install VueJS Tour with yarn

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/getting-started.md

Use yarn to add VueJS Tour to your project dependencies.

```sh
yarn add @globalhive/vuejs-tour
```

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

### Vue.js Tour TypeScript Types and Usage Example

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

All public types are exported from the package root for type safety. Includes an example of a typed composable wrapping tour control methods.

```typescript
import type {
  ITourStep,
  VTourProps,
  VTourEvents,
  VTourEmits,
  VTourData,
  VTourExposedMethods,
  ButtonLabels,
  SaveToLocalStorage,
  JumpOptions,
  NanoPopPosition,
} from '@globalhive/vuejs-tour';

// Example: typed composable that wraps tour control
import { ref } from 'vue';
import { VTour } from '@globalhive/vuejs-tour';

function useTour(steps: ITourStep[]) {
  const tour = ref<InstanceType<typeof VTour>>();

  const start = () => tour.value?.startTour();
  const reset = () => tour.value?.resetTour(true);
  const jump = (i: number) => tour.value?.goToStep(i);

  return { tour, start, reset, jump };
}

```

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

### Delay Tour Start with `startDelay` Prop

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/start-options.md

Utilize the `startDelay` prop to postpone the tour's commencement by a specified number of milliseconds. This allows users to acclimate to the page before the tour begins.

```vue
<template>
  <VTour :steps="steps" ref="vTour"/> // [!code --]
  <VTour :steps="steps" ref="vTour" startDelay='1000'/> // [!code ++]
  ...
</template>
```

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

### Manually Start Tour with startTour Method in Vue.js

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/create-a-tour.md

Reference the VTour component using a template ref and call its `startTour` method to programmatically begin the tour. Ensure the ref is correctly assigned.

```vue
<script setup lang='ts'>
    import HelloWorld from './components/HelloWorld.vue';
    import { VTour } from '@globalhive/vuejs-tour';
    import '@globalhive/vuejs-tour/dist/style.css';
    import { ref } from 'vue';
    
    const steps = [...];
    const vTour = ref(); 
    vTour.value.startTour();
</script>

<template>
  <VTour :steps="steps" ref="vTour"/>
  <div>
    <a href="https://vitejs.dev" target="_blank">
      <img src="/vite.svg" class="logo" alt="Vite logo" />
    </a>
    <a href="https://vuejs.org/" target="_blank">
      <img src="./assets/vue.svg" class="logo vue" alt="Vue logo" />
    </a>
  </div>
  <HelloWorld msg="Vite + Vue" />
</template>
```

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

### Jump Options Priority Example

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/jump-options.md

Demonstrates how step-specific options override global prop options. Only duration is overridden here; offset and a11y retain global values.

```typescript
// Global defaults
const globalJumpOptions = {
  duration: 1000,
  offset: -100,
  a11y: true,
};

// Step overrides
const steps = [
  {
    target: '#step1',
    content: 'Step 1',
    jumpOptions: {
      duration: 300, // Only override duration
      // offset: still -100 from global
      // a11y: still true from global
    },
  },
];

```

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

### Focus Management for Tour Start and Stop

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/accessibility.md

This TypeScript code manages focus by storing the previously focused element before the tour starts and restoring it when the tour stops. This is crucial for maintaining user orientation and accessibility, especially when `enableA11y` is true.

```typescript
let previousFocus: HTMLElement | null = null;

const startTour = async () => {
  if (props.enableA11y && typeof document !== 'undefined') {
    previousFocus = document.activeElement as HTMLElement;
  }
  // ... tour starts
  if (props.enableA11y) {
    await nextTick();
    _Tooltip.value?.focus();
  }
};

const stopTour = () => {
  if (props.enableA11y && previousFocus) {
    previousFocus.focus();
    previousFocus = null;
  }
};
```

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

### Import Custom CSS File for Theming

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/css-theme.md

Replace the default tour styles import with a custom CSS file import in your component's script setup.

```vue
<script setup lang='ts'>
    //...
    import '@globalhive/vuejs-tour/dist/style.css'; // [!code --]
    import './custom-theme.css'; // [!code ++]
</script>
```

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

### Per-Step Accessibility Labels in VTour

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/accessibility.md

Example demonstrating how to set custom `ariaLabel` for individual tour steps to provide descriptive labels for screen readers.

```vue
<script setup>
const steps = [
  {
    target: '#welcome',
    content: 'Welcome to our app!',
    ariaLabel: 'Welcome step: Introduction to the application',
  },
  {
    target: '#profile',
    content: 'View your profile here',
    ariaLabel: 'Profile step: Learn about your user profile',
  },
];
</script>

<template>
  <VTour :steps="steps" :enableA11y="true" />
</template>
```

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

### Custom Easing Function Configuration

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/jump-options.md

Apply a custom easing function for smoother scroll animations by setting the `easing` property in `jump-options`. This example uses 'easeInOutCubic'.

```vue
<template>
  <VTour
    :steps="steps"
    :jump-options="{
      duration: 800,
      easing: 'easeInOutCubic', // Smoother animation
    }"
  />
</template>

```

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

### Configuring Multiple Step Placements

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/using-placement.md

Demonstrates configuring multiple tour steps with different `placement` values, including the default.

```vue
<script setup>
import VTour from '../../src/components/VTour.vue';
import "../../src/style/style.scss";

const steps = [{
  target: '[data-step="0"]',
  content: 'Placement: top',
  placement: 'top'
}
,{ target: '[data-step="0"]', content: 'Placement: right (default)'}
,{ target: '[data-step="0"]', content: 'Placement: bottom', placement: 'bottom' }
,{ target: '[data-step="0"]', content: 'Placement: left', placement: 'left' }];
</script>

<VTour :steps="steps" autoStart saveToLocalStorage='never' noScroll />

<div class="custom-block example">
    <p data-step="0">Target</p>
</div>
```

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

### goToStep(index)

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Navigates the tour directly to a specified step using its zero-based index. This method triggers the `onBefore` callback for the target step and handles scrolling. Invalid indices are ignored and a warning is logged to the console.

```APIDOC
## `goToStep(index)`

### Description
Jumps directly to any step by zero-based index. Fires the step's `onBefore` callback and scrolls to the target. Invalid indices are silently ignored with a `console.warn`.

### Method Signature
`goToStep(index: number): Promise<void>`

### Parameters
#### Path Parameters
- **index** (number) - Required - The zero-based index of the step to navigate to.
```

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

### ITourStep Configuration Options

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Configure individual tour steps using the ITourStep interface. Required fields are 'target' and 'content'. Optional fields control placement, highlighting, backdrop, scrolling, callbacks, and accessibility.

```typescript
import type { ITourStep } from '@globalhive/vuejs-tour';

const steps: ITourStep[] = [
  {
    // Required: any valid CSS selector
    target: '#profile-menu',
    // Required: HTML string displayed inside the tooltip
    content: '<strong>Your Profile</strong><br>Manage account settings here.',
    // Tooltip placement relative to target (nanopop NanoPopPosition values)
    // Options: 'top', 'bottom', 'left', 'right', and variants like 'top-start', etc.
    placement: 'bottom',
    // Outline the target element with a highlight ring
    highlight: true,
    // Show a dark semi-transparent backdrop behind the tooltip
    backdrop: true,
    // Skip auto-scrolling to the target for this step
    noScroll: false,
    // Step-specific scroll animation options (overrides global jumpOptions)
    jumpOptions: { duration: 300, offset: -80, easing: 'easeInCubic' },
    // Async callback executed BEFORE this step is shown
    onBefore: async () => {
      await someApiCall(); // tour waits for this to resolve
    },
    // Async callback executed AFTER this step is shown
    onAfter: async () => {
      console.log('Step shown');
    },
    // Custom aria-label for screen readers on this step
    ariaLabel: 'Profile menu tour step',
  },
];
```

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

### Implement Per-Step Callbacks with onBefore and onAfter

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Define asynchronous callbacks that execute before a step is displayed ('onBefore') and after it's shown ('onAfter'). The tour waits for any Promises returned by these callbacks to resolve before proceeding.

```typescript
import type { ITourStep } from '@globalhive/vuejs-tour';

const steps: ITourStep[] = [
  {
    target: '#lazy-section',
    content: 'This section was loaded just for you.',
    onBefore: async () => {
      // Fetch data or perform DOM mutations before the tooltip appears
      await fetch('/api/load-section').then(r => r.json());
      document.getElementById('lazy-section')!.style.display = 'block';
    },
    onAfter: async () => {
      // Fire analytics or trigger follow-up logic after step is shown
      await fetch('/api/track', {
        method: 'POST',
        body: JSON.stringify({ event: 'tour_step_viewed', target: '#lazy-section' }),
      });
    },
  },
  {
    target: '#summary',
    content: 'Summary loaded dynamically.',
    onBefore: () =>
      new Promise<void>((resolve) =>
        setTimeout(() => {
          // Simulate async data load with 500ms delay
          resolve();
        }, 500)
      ),
  },
];
```

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

### Handle Tour Events

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Listen for tour lifecycle events: `onTourStart`, `onTourEnd`, and `onTourStep`. The `onTourStep` event provides the current zero-based step index.

```vue
<script setup lang="ts">
import { VTour } from '@globalhive/vuejs-tour';

const steps = [
  { target: '#s1', content: 'Step 1' },
  { target: '#s2', content: 'Step 2' },
];

function handleStart() {
  console.log('Tour started');
}

function handleEnd() {
  console.log('Tour finished');
}

function handleStep(stepIndex: number) {
  // stepIndex is 0-based
  console.log(`Now showing step ${stepIndex + 1} of ${steps.length}`);
  // e.g. track analytics: analytics.track('tour_step', { step: stepIndex })
}
</script>

<template>
  <VTour
    :steps="steps"
    autoStart
    @onTourStart="handleStart"
    @onTourEnd="handleEnd"
    @onTourStep="handleStep"
  />
</template>
```

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

### nextStep() and lastStep()

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Provides programmatic control to advance to the next step or go back to the previous step in the tour. These methods mirror the functionality of the default 'Next' and 'Back' navigation buttons.

```APIDOC
## `nextStep()` and `lastStep()`

### Description
Programmatically advance or go back one step. These are the same functions wired to the Next/Back buttons.

### Method Signatures
`nextStep(): Promise<void>`
`lastStep(): Promise<void>`

### Parameters
None
```

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

### Enable Backdrop Per Step

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/step-using-a-backdrop.md

Set the `backdrop` option to `true` within a step's configuration to enable the overlay for that specific step.

```vue
<script setup>
  const steps = [{
    target: '[data-step=0]',
    content: 'Text Content',
    backdrop: true // [!code ++]
  }];
</script>
```

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

### Basic onBefore Event Usage

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/the-onbefore-event.md

Use the onBefore event to execute synchronous code before a step is shown. This is suitable for simple checks or actions.

```vue
<script setup>
  const steps = [{
    target: '[data-step=0]',
    content: 'Text Content',
    onBefore: () => { // [!code ++:3]
      // Do something before the step is shown
    }
  }];
</script>
```

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

### ITourStep Interface

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/the-step-type.md

Defines the structure for a single step in a tour. Each property controls a specific aspect of the step's appearance and behavior.

```APIDOC
## ITourStep Interface

### Description
Defines the structure for a single step in a tour. Each property controls a specific aspect of the step's appearance and behavior.

### Properties
- **target** (string) - Required - The CSS selector for the element to which the step will be attached.
- **content** (string) - Required - The HTML content to display within the step.
- **placement** (NanoPopPosition) - Optional - Specifies the position of the step relative to the target element (e.g., 'top', 'bottom', 'left', 'right').
- **onBefore** (() => Promise<void>) - Optional - A callback function executed just before the step is displayed. Can be used for asynchronous operations.
- **onAfter** (() => Promise<void>) - Optional - A callback function executed immediately after the step is displayed. Can be used for asynchronous operations.
- **highlight** (boolean) - Optional - If true, the target element will be visually highlighted.
- **backdrop** (boolean) - Optional - If true, a backdrop will be shown behind the step, dimming the rest of the page.
- **noScroll** (boolean) - Optional - If true, scrolling to the target element will be disabled.
```

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

### Define Tour Steps in Vue.js

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/create-a-tour.md

Create an array of steps for the tour, where each step specifies a CSS selector for the target element and the content to display.

```vue
<script setup lang='ts'>
    import HelloWorld from './components/HelloWorld.vue';
    import { VTour } from '@globalhive/vuejs-tour';
    import '@globalhive/vuejs-tour/dist/style.css';
    
    const steps = [{
        target: '[data-step="0"]',
        content: 'Step 1',
    },{
        target: '.some-class',
        content: 'Step 2',
    },{
        target: '#some-id',
        content: 'Step 3',
    }];
</script>
```

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

### Manual Navigation with nextStep() and lastStep()

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Control tour progression programmatically using `nextStep()` to advance and `lastStep()` to go back. These functions mirror the behavior of the default navigation buttons.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { VTour } from '@globalhive/vuejs-tour';

const tour = ref<InstanceType<typeof VTour>>();
const steps = [
  { target: '#a', content: 'Step A' },
  { target: '#b', content: 'Step B' },
  { target: '#c', content: 'Step C' },
];
</script>

<template>
  <div>
    <button @click="tour?.lastStep()">← Back</button>
    <button @click="tour?.nextStep()">Next →</button>
  </div>
  <VTour ref="tour" :steps="steps" autoStart :hideSkip="true" />
</template>
```

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

### Navigate to Specific Step with goToStep

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Use `goToStep(index)` to jump to a specific step by its zero-based index. This method fires the `onBefore` callback and scrolls to the target. Invalid indices are ignored with a console warning.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { VTour } from '@globalhive/vuejs-tour';

const tour = ref<InstanceType<typeof VTour>>();
const steps = [
  { target: '#intro', content: 'Introduction' },
  { target: '#settings', content: 'Settings panel' },
  { target: '#advanced', content: 'Advanced options' },
];

async function jumpToSettings() {
  await tour.value?.goToStep(1); // jumps to 'Settings panel'
}
</script>

<template>
  <button @click="jumpToSettings">Show Settings Step</button>
  <VTour ref="tour" :steps="steps" autoStart />
</template>
```

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

### Configure Tour Progress Persistence with localStorage

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Control when tour progress is saved to localStorage. Options include 'never' (default), 'step' (saves current step), and 'end' (saves only on completion). The storage key is 'vjt-<name>'.

```vue
<script setup lang="ts">
import { VTour } from '@globalhive/vuejs-tour';

const steps = Array.from({ length: 5 }, (_, i) => ({
  target: `#onboarding-${i + 1}`,
  content: `Onboarding step ${i + 1}`,
}));
</script>

<template>
  <!--
    'never' (default): no persistence, always starts from step 0
    'step':  saves the current step index after each step; resumes from that step on next visit
    'end':   saves 'true' only when tour is fully completed; startTour() no-ops if flag is set
  -->
  <VTour
    name="onboarding"
    :steps="steps"
    autoStart
    saveToLocalStorage="step"
  />

  <!--
    Reset programmatically:
      tour.value?.resetTour()           // clears flag, doesn't restart
      tour.value?.resetTour(true)       // clears flag and restarts
    Manual clear:
      localStorage.removeItem('vjt-onboarding')
  -->
</template>
```

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

### Configure Local Storage Persistence for Tours

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/multiple-tours.md

Control tour progress saving using the `saveToLocalStorage` prop. Options include 'never' (default), 'step' (save after each step), and 'end' (save only on completion). Each tour's progress is isolated using its `name` prop.

```vue
<script setup lang="ts">
// ...
const steps = [...];
</script>

<template>
  <!-- No persistence (default) -->
  <VTour :steps="steps" autoStart />

  <!-- Save current step index after each step -->
  <VTour :steps="steps" name="onboarding" autoStart saveToLocalStorage="step" />

  <!-- Mark tour as completed only at the end -->
  <VTour :steps="steps" name="tips" autoStart saveToLocalStorage="end" />
</template>
```

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

### Override SCSS Variables for Theming

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/css-theme.md

Create a SCSS file to override default tour variables, import the default theme, and then import your custom file in the component.

```scss
$vjt__tooltip_color: rgb(15 23 42);
$vjt__tooltip_background: rgb(241 245 249);
$vjt__action_button_color: rgb(15 23 42);
$vjt__action_button_color_hover: rgb(241 245 249);
$vjt__action_button_background_hover: rgb(15 23 42);
$vjt__action_button_border: 1px solid rgb(15 23 42);

@import '@globalhive/vuejs-tour/src/style.scss';
```

```vue
<script setup lang='ts'>
  //...
  import '../white.scss';
</script>

<template>
  <VTour .../>
</template>
```

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

### Define Text Content for a Tour Step

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/define-the-content.md

Use the `content` property to set plain text for a tour step. Ensure the target element exists.

```vue
<script setup>
  const steps = [{
    target: '[data-step=0]',
    content: 'Text Content'
  }];
</script>
```

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

### Execute Code After Step Display

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/the-onafter-event.md

Use the onAfter event to run custom logic after a step is shown. This handler is called directly after the step's content is rendered.

```vue
<script setup>
  const steps = [{
    target: '[data-step=0]',
    content: 'Text Content',
    onAfter: () => {
      // Do something after the step is shown
    }
  }];
</script>
```

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

### Delay Step Execution with Promises

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/the-onafter-event.md

Leverage the asynchronous nature of onAfter by returning a Promise. This allows you to introduce delays or wait for other asynchronous operations before the tour proceeds.

```vue
<script setup>
  const steps = [{
    target: '[data-step=0]',
    content: 'Text Content',
    onAfter: new Promise((resolve) => {
      setTimeout(() => {
        // Do something after the step is shown
        resolve();
      }, 1000);
    })
  }];
</script>
```

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

### Configure Local Storage Saving for VTour

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/saving-progress.md

Use the `saveToLocalStorage` prop to control how tour progress is saved. Set to 'step' to save after each step, 'end' to save only upon completion (default), or 'never' to disable saving.

```vue
<script setup lang='ts'>
    // ...
    const steps = [...];
</script>

<template>
  <VTour :steps="steps" autoStart :margin="0"/> // [!code --] 
  <VTour :steps="steps" autoStart saveToLocalStorage='step'/> // [!code ++]
  ...
</template>
```

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

### Enable Highlight for a Step

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/step-highlight-target.md

Set the `highlight` option to `true` within a step's configuration to enable the highlight effect for that specific step.

```vue
<script setup>
  const steps = [{
    target: '[data-step=0]',
    content: 'Text Content',
    highlight: true // [!code ++]
  }];
</script>
```

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

### Asynchronous onBefore Event with Promise

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/the-onbefore-event.md

Leverage the onBefore event with a Promise to perform asynchronous operations, such as delaying the step display. The step will only show after the promise resolves.

```vue
<script setup>
  const steps = [{
    target: '[data-step=0]',
    content: 'Text Content',
    onBefore: new Promise((resolve) => { // [!code ++:6]
      setTimeout(() => {
        // Do something before the step is shown
        resolve();
      }, 1000);
    })
  }];
</script>
```

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

### Define HTML Content for a Tour Step

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/define-the-content.md

Use the `content` property to set HTML content for a tour step, enabling rich text formatting like bold, italics, and line breaks. Ensure the target element exists.

```vue
<script setup>
  const steps = [{
    target: '[data-step=0]',
    content: '<b>Bold</b><br><i>Italic</i><br><u>Underline</u>'
  }];
</script>
```

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

### Events: onTourStart, onTourEnd, onTourStep

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

The VTour component emits three distinct events to signal lifecycle changes: `onTourStart` when the tour begins, `onTourEnd` when it concludes, and `onTourStep` whenever the tour advances to a new step, providing the current step's index.

```APIDOC
## Events

### Description
The component emits three events. `onTourStep` carries the zero-based step index.

### Emitted Events
- **`onTourStart`**: Emitted when the tour begins.
- **`onTourEnd`**: Emitted when the tour is ended.
- **`onTourStep`**: Emitted when the tour moves to a new step. It receives the zero-based step index as a payload.

### Event Payloads
- **`onTourStep`**: `stepIndex: number` (zero-based index of the current step)
```

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

### ITourStep Interface Definition

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/the-step-type.md

Defines the structure for a single step in a tour, including target element, content, placement, lifecycle hooks, and visual options.

```typescript
export interface ITourStep {
    target: string; // The target element to attach the step to
    content: string; // The content of the step
    placement?: NanoPopPosition; // The placement of the step
    onBefore?: () => Promise<void>; // Called before the step is shown
    onAfter?: () => Promise<void>; // Called after the step is shown
    highlight?: boolean; // Highlight the target element
    backdrop?: boolean; // Show a backdrop if set
    noScroll?: boolean; // Disable scrolling if set
}
```

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

### Defining Placement Types

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/using-placement.md

TypeScript types for defining the possible values of the `placement` property.

```typescript
type Direction = 'top' | 'left' | 'bottom' | 'right';
type Alignment = 'start' | 'middle' | 'end';
export type NanoPopPosition = `${Direction}-${Alignment}` | Direction;
```

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

### VueJS Tour Component Usage

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/index.md

This snippet demonstrates how to import and use the VTour component in a Vue 3 application. It defines tour steps with targets, content (including HTML), and placement options. The `onTourEnd` function redirects the user upon tour completion. Configure tour behavior with props like `autoStart`, `highlight`, and `saveToLocalStorage`.

```vue
<script setup>
import VTour from '../src/components/VTour.vue';
import "../src/style/style.scss";


const steps = [{
    target: '.image-src',
    content: 'Welcome to the VueJS Tour documentation!',
    placement: 'left'
    },{
    target: '.image-src',
    content: '<div style="text-align: end">Maybe right is better?</div>'
    },{
    target: '.VPFooter > .container > .copyright > a',
    content: 'Made with ❤️ by <a href="https://github.com/GlobalHive/vuejs-tour">Global Hive</a>',
    placement: 'top'
    },{
    target: 'a[href="/vuejs-tour/reference/coming-soon.html"]',
    content: '<center style="padding: 12px">Looking for the Reference?</center>',
    placement: 'bottom'
    },{
    target: 'p.tagline',
    content: 'With full <b>HTML</b> <u>support</u>!<br><img style="margin-top: 8px" src="https://media1.tenor.com/m/AET3FD31-rgAAAAC/slow-clap-cheers.gif"/>',
    placement: 'left'
    },{
    target: '.brand',
    content: "Let's get started! 🚀",
    placement: 'bottom'
    }];

const onTourEnd = () => {
    window.location.href = '/vuejs-tour/guide/what-is-vuejs-tour.html';
}
</script>

<VTour :steps="steps" autoStart highlight saveToLocalStorage="never" @onTourEnd.once="onTourEnd"/>
```

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

### Keyboard Navigation Handler

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/accessibility.md

Implement this TypeScript function to handle keyboard navigation within the tour. It supports Escape to end the tour, and Right Arrow/Enter to proceed to the next step. Left Arrow navigates to the previous step if available. Ensure `tourVisible`, `enableA11y`, and `keyboardNav` are true before activation.

```typescript
const onKeydown = (event: KeyboardEvent): void => {
  if (!tourVisible.value || !props.enableA11y || !props.keyboardNav) return;

  switch (event.key) {
    case 'Escape':
      endTour();
      event.preventDefault();
      break;
    case 'ArrowRight':
    case 'Enter':
      nextStep();
      event.preventDefault();
      break;
    case 'ArrowLeft':
      if (currentStepIndex.value > 0) {
        lastStep();
        event.preventDefault();
      }
      break;
  }
};
```

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

### resetTour(shouldRestart?)

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Clears the localStorage entry for this tour and resets the current step to 0. Optionally restarts the tour immediately.

```APIDOC
## `resetTour(shouldRestart?)` — Reset State

Clears the localStorage entry for this tour and resets the current step to 0. Pass `true` to also restart the tour immediately.

### Method Signature

`tour.value?.resetTour(shouldRestart?: boolean)`

### Parameters

- **shouldRestart** (boolean) - Optional. If `true`, restarts the tour immediately after resetting.

### Usage Example

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { VTour } from '@globalhive/vuejs-tour';

const tour = ref<InstanceType<typeof VTour>>();
const steps = [
  { target: '#el1', content: 'Welcome back!' },
  { target: '#el2', content: 'Here is what\'s new.' },
];

function showAgain() {
  // Clear completion flag and restart from step 0
  tour.value?.resetTour(true);
}
</script>

<template>
  <button @click="showAgain">Show Tour Again</button>
  <VTour ref="tour" name="onboarding" :steps="steps" saveToLocalStorage="end" />
</template>
```
```

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

### JumpOptions Interface

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/jump-options.md

Defines the available configuration options for scroll animations. Customize duration, offset, callback, easing, and accessibility.

```typescript
interface JumpOptions {
  /** Duration of scroll animation in milliseconds (default: 500) */
  duration?: number;

  /** Vertical offset in pixels from target element (default: -100) */
  offset?: number;

  /** Callback function to execute after scroll completes */
  callback?: () => void;

  /**
   * Easing function name (default: 'easeInOutQuad')
   * Valid values: 'easeInQuad', 'easeOutQuad', 'easeInOutQuad', 'easeInCubic',
   * 'easeOutCubic', 'easeInOutCubic', 'easeInQuart', 'easeOutQuart', 'easeInOutQuart',
   * 'easeInQuint', 'easeOutQuint', 'easeInOutQuint'
   */
  easing?: string;

  /** Whether to focus the element for accessibility (default: false) */
  a11y?: boolean;
}

```

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

### Global Jump Options Configuration

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/jump-options.md

Set default jump options for all tour steps by passing an object to the `jump-options` prop. This configures the scroll animation for the entire tour.

```vue
<template>
  <VTour
    :steps="steps"
    :jump-options="{
      duration: 1000,
      offset: -50,
      easing: 'easeInOutQuad',
      a11y: true,
    }"
  />
</template>

```

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

### End Tour with endTour()

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Terminate the tour and optionally mark it as complete in local storage by setting `saveToLocalStorage` to `'end'`. This action also emits the `onTourEnd` event.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { VTour } from '@globalhive/vuejs-tour';

const tour = ref<InstanceType<typeof VTour>>();
const steps = [{ target: '#main', content: 'All done!' }];

function forceDone() {
  tour.value?.endTour();
  // localStorage.getItem('vjt-myapp') === 'true' after this call
}
</script>

<template>
  <button @click="forceDone">Mark Tour Complete</button>
  <VTour ref="tour" name="myapp" :steps="steps" saveToLocalStorage="end" />
</template>
```

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

### stopTour()

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Immediately hides the tour and removes all highlights and backdrop without marking it as completed in localStorage.

```APIDOC
## `stopTour()` — Stop Without Completing

Immediately hides the tour and removes all highlights and backdrop without marking it as completed in localStorage.

### Method Signature

`tour.value?.stopTour()`

### Usage Example

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { VTour } from '@globalhive/vuejs-tour';

const tour = ref<InstanceType<typeof VTour>>();
const steps = [
  { target: '#el1', content: 'Step 1' },
  { target: '#el2', content: 'Step 2' },
];
</script>

<template>
  <!-- User can dismiss tour without it being recorded as "completed" -->
  <button @click="tour?.stopTour()">Dismiss Tour</button>
  <VTour ref="tour" :steps="steps" autoStart />
</template>
```
```

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

### content Slot

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Allows for custom rendering of the tooltip content area. This slot provides access to `currentStepIndex` and `currentStepData`, enabling dynamic and personalized content display within each tour step.

```APIDOC
## `content` Slot

### Description
Replace the default HTML-rendered content area with any custom markup. Receives `currentStepIndex` (number) and `currentStepData` (ITourStep) as slot props.

### Slot Props
- **`currentStepIndex`** (number): The zero-based index of the currently displayed step.
- **`currentStepData`** (object): An object containing the data for the current step, including `target` and `content`.
```

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

### Enable Backdrop Globally

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/step-using-a-backdrop.md

You can enable the highlight effect globally by setting the `backdrop` prop in the `VTour` component. This applies the backdrop to all steps unless overridden per step.

```vue
<script setup>
import { ref } from 'vue';
import VTour from '../../src/components/VTour.vue';
import "../../src/style/style.scss";

const vTourComponent = ref();
const steps = [{ target: '[data-step="0"]', content: 'Click "Done" to close the Tooltip', backdrop: true }];

function clickToStart() {
    vTourComponent.value.startTour();
}
</script>

<VTour ref="vTourComponent" :steps="steps" saveToLocalStorage='never' noScroll/>

<div class="custom-block example">
    <button data-step="0" @click="clickToStart">Click To Start<br>With Backdrop Enabled</button>
</div>
```

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

### Switch Between Tours Manually

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/multiple-tours.md

If the prop-change watcher is disabled, call `startTour()` manually after updating the `tourSteps` and `tourName` props to switch between tours.

```vue
function switchTour() {
  if (tourName.value === 'tour1') {
    tourSteps.value = tourSteps2;
    tourName.value = 'tour2';
  } else {
    tourSteps.value = tourSteps1;
    tourName.value = 'tour1';
  }
  vTour.value?.startTour(); // manual restart when watcher is disabled
}
```

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

### VTour Component Props Configuration

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Configure the VTour component using its various props to customize tour behavior, appearance, and storage. Ensure all required props like 'steps' are provided.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { VTour } from '@globalhive/vuejs-tour';
import type { ITourStep, ButtonLabels, JumpOptions } from '@globalhive/vuejs-tour';

const steps: ITourStep[] = [
  { target: '#step1', content: 'Step one content' },
  { target: '#step2', content: 'Step two content' },
];

const customLabels: Partial<ButtonLabels> = {
  next: 'Forward',
  back: 'Previous',
  done: 'Finish',
  skip: 'Cancel',
};

const scrollOptions: Partial<JumpOptions> = {
  duration: 800,
  offset: -120,
  easing: 'easeInOutCubic',
  a11y: true,
};
</script>

<template>
  <VTour
    name="onboarding"          <!-- Unique tour name; scopes IDs and localStorage keys (default: 'tour') -->
    :steps="steps"             <!-- Required: array of ITourStep -->
    :backdrop="true"           <!-- Show semi-transparent backdrop (default: false) -->
    :autoStart="true"          <!-- Auto-start on mount (default: false) -->
    :startDelay="1000"         <!-- Delay before starting in ms (default: 0) -->
    :highlight="true"          <!-- Highlight target elements by default (default: false) -->
    :margin="10"               <!-- Pixel gap between tooltip and target (default: 8) -->
    :buttonLabels="customLabels"    <!-- Override button text -->
    saveToLocalStorage="step"  <!-- 'never' | 'step' | 'end' (default: 'never') -->
    :hideSkip="false"          <!-- Hide the skip button (default: false) -->
    :hideArrow="false"         <!-- Hide the tooltip arrow (default: false) -->
    :noScroll="false"          <!-- Disable auto-scrolling globally (default: false) -->
    :resizeTimeout="250"       <!-- Resize event debounce in ms (default: 250) -->
    defaultPlacement="right"   <!-- Fallback placement when step doesn't specify one -->
    :jumpOptions="scrollOptions"    <!-- Global scroll animation options -->
    :enableA11y="true"         <!-- Enable ARIA attributes and focus management (default: false) -->
    :keyboardNav="true"        <!-- Enable keyboard navigation (default: true) -->
    ariaLabel="Product tour"   <!-- ARIA label for the tour dialog (default: 'Guided tour') -->
    :teleportDelay="100"       <!-- Delay in ms for Teleport to render (default: 100) -->
  />
</template>

```

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

### Enable Highlight Globally

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/step-highlight-target.md

To apply the highlight effect to all steps by default, set the `highlight` prop on the `VTour` component. This avoids needing to set it for each individual step.

```vue
<script setup>
import VTour from '../../src/components/VTour.vue';
import "../../src/style/style.scss";

const steps = [{ target: '[data-step="0"]', content: 'Target highlighted', highlight: true }];

</script>
<VTour :steps="steps" autoStart saveToLocalStorage='never' noScroll/>

<div class="custom-block example">
    <p data-step="0">Target</p>
</div>
```

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

### endTour()

Source: https://context7.com/globalhive/vuejs-tour/llms.txt

Terminates the current tour and optionally records a completion flag in local storage if `saveToLocalStorage` is configured. This method also emits the `onTourEnd` event.

```APIDOC
## `endTour()`

### Description
Stops the tour and, depending on `saveToLocalStorage`, records a completion flag (`'true'`) in localStorage. Emits the `onTourEnd` event.

### Method Signature
`endTour(): Promise<void>`

### Parameters
None
```

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

### Targeting with CSS Classes

Source: https://github.com/globalhive/vuejs-tour/blob/master/docs/guide/setting-a-target.md

Specify the target element for a tour step using a CSS class selector. The element in your template must have the matching class.

```vue
<script setup>
  const steps = [{
    target: '.class-of-element',
    content: 'Content'
  }];
</script>

<template>
  <div class="class-of-element">Element</div>
</template>
```