Skip to content

feat(Tour): add guided tour component #5781

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
solidusite wants to merge 2 commits into
base: v4
Choose a base branch
from
Draft

feat(Tour): add guided tour component #5781

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a10cf4c
feat(Tour): add guided tour component with customizable steps, labels…
solidusite Dec 29, 2025
26f6459
chore(Tour): locale default preset
solidusite Dec 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions docs/app/components/content/examples/tour/TourBasicExample.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
<script setup lang="ts">
const open = ref(false)
const step = ref(0)

const steps = [
{
target: '#tour-target-1',
title: 'Welcome',
description: 'This is the first step of the tour',
body: 'Click next to continue to the next step.'
},
{
target: '#tour-target-2',
title: 'Second Step',
description: 'This is the second step',
body: 'You can customize each step with title, description, and body.'
},
{
target: '#tour-target-3',
title: 'Final Step',
description: 'This is the last step',
body: 'Click finish to close the tour.'
}
]
</script>

<template>
<div class="space-y-4">
<div id="tour-target-1" class="p-4 border border-default rounded-lg bg-default">
<p class="font-semibold">
Target Element 1
</p>
<p class="text-sm text-muted">
This element will be highlighted in the first step
</p>
</div>
<div id="tour-target-2" class="p-4 border border-default rounded-lg bg-default">
<p class="font-semibold">
Target Element 2
</p>
<p class="text-sm text-muted">
This element will be highlighted in the second step
</p>
</div>
<div id="tour-target-3" class="p-4 border border-default rounded-lg bg-default">
<p class="font-semibold">
Target Element 3
</p>
<p class="text-sm text-muted">
This element will be highlighted in the final step
</p>
</div>
<UButton @click="open = true">
Start Tour
</UButton>
</div>

<UTour v-model:open="open" v-model:step="step" :steps="steps" />
</template>
61 changes: 61 additions & 0 deletions docs/app/components/content/examples/tour/TourCustomLabelsExample.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
<script setup lang="ts">
const open = ref(false)
const step = ref(0)

const steps = [
{
target: '#tour-target-4',
title: 'First Step',
description: 'Custom button labels',
nextLabel: 'Continue'
},
{
target: '#tour-target-5',
title: 'Middle Step',
description: 'Custom previous label',
prevLabel: 'Go Back',
nextLabel: 'Next Step'
},
{
target: '#tour-target-6',
title: 'Last Step',
description: 'Custom finish label',
prevLabel: 'Previous',
finishLabel: 'Complete Tour'
}
]
</script>

<template>
<div class="space-y-4">
<div id="tour-target-4" class="p-4 border border-default rounded-lg bg-default">
<p class="font-semibold">
Step 1
</p>
<p class="text-sm text-muted">
Has custom "Continue" button
</p>
</div>
<div id="tour-target-5" class="p-4 border border-default rounded-lg bg-default">
<p class="font-semibold">
Step 2
</p>
<p class="text-sm text-muted">
Has custom "Go Back" and "Next Step" buttons
</p>
</div>
<div id="tour-target-6" class="p-4 border border-default rounded-lg bg-default">
<p class="font-semibold">
Step 3
</p>
<p class="text-sm text-muted">
Has custom "Complete Tour" finish button
</p>
</div>
<UButton @click="open = true">
Start Tour
</UButton>
</div>

<UTour v-model:open="open" v-model:step="step" :steps="steps" />
</template>
54 changes: 54 additions & 0 deletions docs/app/components/content/examples/tour/TourLoopExample.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
<script setup lang="ts">
const open = ref(false)
const step = ref(0)
const loop = ref(true)

const steps = [
{
target: '#tour-target-7',
title: 'Step 1',
description: 'First step of the tour'
},
{
target: '#tour-target-8',
title: 'Step 2',
description: 'Second step of the tour'
},
{
target: '#tour-target-9',
title: 'Step 3',
description: 'Third step of the tour'
}
]
</script>

<template>
<div class="space-y-4">
<div id="tour-target-7" class="p-4 border border-default rounded-lg bg-default">
<p class="font-semibold">
Target 1
</p>
</div>
<div id="tour-target-8" class="p-4 border border-default rounded-lg bg-default">
<p class="font-semibold">
Target 2
</p>
</div>
<div id="tour-target-9" class="p-4 border border-default rounded-lg bg-default">
<p class="font-semibold">
Target 3
</p>
</div>
<div class="flex items-center gap-4">
<UButton @click="open = true">
Start Tour
</UButton>
<div class="flex items-center gap-2">
<span class="text-sm text-muted">Loop</span>
<USwitch v-model="loop" size="sm" />
</div>
</div>
</div>

<UTour v-model:open="open" v-model:step="step" :steps="steps" :loop="loop" />
</template>
58 changes: 58 additions & 0 deletions docs/app/components/content/examples/tour/TourModalExample.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
<script setup lang="ts">
const open = ref(false)
const step = ref(0)
const modal = ref(true)

const steps = [
{
target: '#tour-target-modal-1',
title: 'Modal Tour',
description: 'When modal is enabled, interaction with outside elements is disabled',
body: 'Try clicking on the buttons below - they will be disabled while the tour is open.'
},
{
target: '#tour-target-modal-2',
title: 'Second Step',
description: 'Only the tour content is visible to screen readers',
body: 'This helps ensure accessibility and focus management.'
}
]
</script>

<template>
<div class="space-y-4">
<div id="tour-target-modal-1" class="p-4 border border-default rounded-lg bg-default">
<p class="font-semibold">
Target Element 1
</p>
<p class="text-sm text-muted">
This element will be highlighted in the first step
</p>
</div>
<div id="tour-target-modal-2" class="p-4 border border-default rounded-lg bg-default">
<p class="font-semibold">
Target Element 2
</p>
<p class="text-sm text-muted">
This element will be highlighted in the second step
</p>
</div>
<div class="flex items-center gap-4">
<UButton @click="open = true">
Start Tour
</UButton>
<div class="flex items-center gap-2">
<span class="text-sm text-muted">Modal</span>
<USwitch v-model="modal" size="sm" />
</div>
<UButton color="neutral" variant="outline" :disabled="open">
Disabled Button
</UButton>
<UButton color="primary" variant="soft" :disabled="open">
Another Button
</UButton>
</div>
</div>

<UTour v-model:open="open" v-model:step="step" :steps="steps" :modal="modal" />
</template>
94 changes: 94 additions & 0 deletions docs/content/docs/2.components/tour.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
---
description: A guided tour component that highlights elements and displays step-by-step instructions.
category: overlay
links:
- label: Popover
icon: i-custom-reka-ui
to: https://reka-ui.com/docs/components/popover
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxt/ui/blob/v4/src/runtime/components/Tour.vue
---

## Usage

The Tour component allows you to create guided tours that highlight specific elements and display step-by-step instructions.

Each step in the tour can target an element by ID, CSS selector, or a ref function. Use the `steps` prop to define your tour steps.

### Steps

Each step in the tour requires a `target` property that can be:
- A string ID selector (e.g., `'#my-element'`)
- A CSS class selector (e.g., `'.my-class'`)
- A ref function that returns an HTMLElement (e.g., `() => myRef.value`)

Each step can also include:
- `title` - The step title
- `description` - A short description
- `body` - Additional body content
- `nextLabel`, `prevLabel`, `finishLabel` - Custom button labels
- `content` - Popover positioning options
- `dismissible` - Whether the step can be dismissed
- `arrow` - Whether to show an arrow

### Loop

Use the `loop` prop to automatically restart the tour when reaching the last step.

### Custom Labels

You can customize button labels for each step using `nextLabel`, `prevLabel`, and `finishLabel` properties on individual steps.

### Modal

Use the `modal` prop to control whether the tour blocks interaction with outside elements. When set to `true`, interaction with outside elements will be disabled and only tour content will be visible to screen readers.

## Examples

::component-example
---
name: 'tour-basic-example'
---
::

::component-example
---
name: 'tour-loop-example'
---
::

::component-example
---
name: 'tour-custom-labels-example'
---
::

::component-example
---
name: 'tour-modal-example'
---
::

## API

### Props

:component-props

### Slots

:component-slots

### Emits

:component-emits

## Theme

:component-theme

## Changelog

:component-changelog

Loading
Loading