Tour
newLet me show you around. A popover that walks from one element to the next, driven by useTour.
Installation
Usage
<script setup lang="ts">
import {
Tour,
TourClose,
TourContent,
TourDescription,
TourFooter,
TourNext,
TourPrevious,
TourProgress,
TourTitle,
useTour,
} from '@/components/ui/tour'
const card = useTemplateRef('card')
const tour = useTour([
{ target: null, title: 'Welcome', body: 'A quick look around.' },
{ target: 'new-file', title: 'Create', body: 'Start something new here.' },
{ target: () => card.value, title: 'Profile', body: 'Your account lives here.', side: 'left' as const },
])
</script>
<template>
<Button @click="tour.start()">Start the tour</Button>
<Tour v-slot="{ step }" :tour="tour">
<TourContent :side="step.side">
<TourTitle>{{ step.title }}</TourTitle>
<TourDescription>{{ step.body }}</TourDescription>
<TourFooter>
<TourProgress />
<TourPrevious />
<TourNext />
</TourFooter>
<TourClose />
</TourContent>
</Tour>
</template>
useTour holds the steps and which one is showing; Tour puts a single popover on the current step's element and moves it as the tour goes on. You write the steps, so the copy, the fields and the layout are yours: every field besides target rides along to the slot's step, typed. Ported from Nuxt UI's composable of the same name, with parts on top.
A step's target is the element it points at:
- a plain word is an id, so
'header'means#header, never the<header>element; - anything else is a CSS selector:
'#cta','.card','[data-tour="search"]'; - an element, a virtual element (anything with
getBoundingClientRect), or a ref or getter returning one; null, or notarget, centres the step in the viewport, for a welcome or a goodbye.
A target that matches nothing centres the step too, and in development useTour warns about it once.
The popover stays when you click elsewhere on the page and finishes on Escape. When it opens, focus moves to TourNext; when it closes, focus goes back to whatever started the tour. The current target is scrolled into view at each step.
| Option | Description |
|---|---|
initialStep | The step start() opens on. 0 by default. |
loop | Go back to the first step after the last instead of finishing. |
scrollIntoView | false leaves the scroll alone; an object is passed to scrollIntoView. { behavior: 'smooth', block: 'center' } by default. |
It returns open, index, current, total, hasNext, hasPrev, loop, reference (the anchor for a popover of your own), centered, and start(index?), next(), prev(), goTo(index), finish(). next() on the last step finishes, or loops with loop.
Examples
Progress as dots
TourProgress shows "2 / 5" by default. Its slot gets index and total, so anything can stand in, such as a page indicator.
- Plan
- Team
- Repository
API Reference
class is also accepted on every part except Tour and merged over its classes.
Tour
class is also accepted on every part except Tour and merged over its classes with tailwind-merge.
| Prop | Default | Type and description |
|---|---|---|
| tour* | — | UseTourReturn<T>What |
| Slot | Scope and description |
|---|---|
| default | { step: T; index: number; total: number; hasNext: boolean; hasPrev: boolean; }
|
TourContent
| Prop | Default | Type and description |
|---|---|---|
| forceMount | — | booleanKeeps the panel mounted while closed, for animating it with a JavaScript library. |
| memoDependencies | — | unknown[]Values that should re-run the position update when they change. |
| side | — | "top" | "right" | "bottom" | "left"The side of the step's element to open on. Ignored on a centred step. |
| sideOffset | 8 | numberDistance in pixels from the step's element. 8 by default. |
| sideFlip | — | booleanFlips to the opposite side when the preferred one would overflow. |
| align | "center" | "center" | "start" | "end"Alignment against the trigger along the chosen side. |
| alignOffset | — | numberOffset in pixels from the |
| alignFlip | — | booleanFlips the alignment when it would overflow. |
| avoidCollisions | — | booleanKeeps the panel inside the collision boundary by flipping and shifting it. |
| collisionBoundary | — | Element | (Element | null)[] | nullThe element or elements used as the collision boundary. The viewport by default. |
| collisionPadding | 8 | number | Partial<Record<"top" | "right" | "bottom" | "left", number>>Distance in pixels from the boundary edges where collisions start. |
| arrowPadding | — | numberPadding between an arrow and the panel's corners. |
| hideShiftedArrow | — | booleanHides an arrow when the panel is shifted so far that the arrow would not point at the trigger. |
| sticky | — | "partial" | "always"
|
| hideWhenDetached | — | booleanHides the panel when the trigger is scrolled out of view. |
| positionStrategy | — | "absolute" | "fixed"The CSS position used to place the panel. |
| updatePositionStrategy | — | "always" | "optimized"
|
| disableUpdateOnLayoutShift | — | booleanStops recomputing the position when the layout shifts. |
| prioritizePosition | — | booleanKeeps the preferred side and alignment and lets the panel overflow instead of flipping. |
| reference | — | ReferenceElementA virtual element to position against instead of the trigger. |
| dir | — | DirectionReading direction. Mirrors the layout and arrow keys in |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| disableOutsidePointerEvents | — | booleanShuts the page to the pointer while open, as |
| Event | Payload and description |
|---|---|
| escapeKeyDown | [event: KeyboardEvent]Fires on Escape. Call |
| pointerDownOutside | [event: PointerDownOutsideEvent]Fires on a pointer press outside. Call |
| focusOutside | [event: FocusOutsideEvent]Fires when focus moves outside. Call |
| interactOutside | [event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on any press or focus outside. The tour ignores it and stays open. |
| openAutoFocus | [event: Event]Fires when the popover opens. Focus goes to TourNext when there is one; call preventDefault() to keep focus where it is. |
| closeAutoFocus | [event: Event]Fires when the tour ends. Focus returns to the element that started it. |
| Slot | Scope and description |
|---|---|
| default | {}TourTitle, TourDescription, TourFooter and TourClose. |
TourTitle
| Slot | Scope and description |
|---|---|
| default | {}The step's heading. It names the popover. |
TourDescription
| Slot | Scope and description |
|---|---|
| default | {}The step's text. It describes the popover. |
TourFooter
| Slot | Scope and description |
|---|---|
| default | {}TourProgress first, then the buttons, pushed to the end. |
TourProgress
| Slot | Scope and description |
|---|---|
| default | { index: number; total: number; }The step count, "2 / 5" by default. Receives |
TourPrevious
| Prop | Default | Type and description |
|---|---|---|
| variant | "outline" | "outline" | "solid" | "soft" | "subtle" | "ghost" | "link" | nullThe button's variant, |
| color | "neutral" | ButtonColor | (string & {})The button's colour, |
| size | "sm" | ButtonSizeThe button's size, |
| Slot | Scope and description |
|---|---|
| default | {}The label, "Back" by default. Pressing it goes to the previous step; on the first step it is aria-disabled. |
TourNext
| Prop | Default | Type and description |
|---|---|---|
| variant | "solid" | "solid" | "soft" | "subtle" | "outline" | "ghost" | "link" | nullThe button's variant, |
| color | "primary" | ButtonColor | (string & {})The button's colour, |
| size | "sm" | ButtonSizeThe button's size, |
| Slot | Scope and description |
|---|---|
| default | { hasNext: boolean; }The label, "Next", or "Finish" on the last step of a tour that does not loop. Receives |
TourClose
| Slot | Scope and description |
|---|---|
| default | {}The icon, an X by default. Pressing it ends the tour. |
class is also accepted on every part except Tour and merged over its classes with tailwind-merge.
Props
- tour*
UseTourReturn<T>WhatuseTourreturns. The popover opens and moves with it.
Slots
- default
{ step: T; index: number; total: number; hasNext: boolean; hasPrev: boolean; }TourContent, rendered for the current step. Receivesstep, typed after your steps, andindex,total,hasNext,hasPrev.
Props
- forceMount
booleanKeeps the panel mounted while closed, for animating it with a JavaScript library.- memoDependencies
unknown[]Values that should re-run the position update when they change.- side
"top" | "right" | "bottom" | "left"The side of the step's element to open on. Ignored on a centred step.- sideOffset
8 numberDistance in pixels from the step's element. 8 by default.- sideFlip
booleanFlips to the opposite side when the preferred one would overflow.- align
"center" "center" | "start" | "end"Alignment against the trigger along the chosen side.- alignOffset
numberOffset in pixels from thealignposition.- alignFlip
booleanFlips the alignment when it would overflow.- avoidCollisions
booleanKeeps the panel inside the collision boundary by flipping and shifting it.- collisionBoundary
Element | (Element | null)[] | nullThe element or elements used as the collision boundary. The viewport by default.- collisionPadding
8 number | Partial<Record<"top" | "right" | "bottom" | "left", number>>Distance in pixels from the boundary edges where collisions start.- arrowPadding
numberPadding between an arrow and the panel's corners.- hideShiftedArrow
booleanHides an arrow when the panel is shifted so far that the arrow would not point at the trigger.- sticky
"partial" | "always"partialkeeps the panel attached to the trigger while scrolling;alwaysalso lets it detach from the trigger to stay in the boundary.- hideWhenDetached
booleanHides the panel when the trigger is scrolled out of view.- positionStrategy
"absolute" | "fixed"The CSS position used to place the panel.- updatePositionStrategy
"always" | "optimized"alwaysrecomputes the position on every animation frame instead of only on layout changes.- disableUpdateOnLayoutShift
booleanStops recomputing the position when the layout shifts.- prioritizePosition
booleanKeeps the preferred side and alignment and lets the panel overflow instead of flipping.- reference
ReferenceElementA virtual element to position against instead of the trigger.- dir
DirectionReading direction. Mirrors the layout and arrow keys inrtl.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- disableOutsidePointerEvents
booleanShuts the page to the pointer while open, asmodalon the root does.
Emits
- escapeKeyDown
[event: KeyboardEvent]Fires on Escape. CallpreventDefault()to keep it open.- pointerDownOutside
[event: PointerDownOutsideEvent]Fires on a pointer press outside. CallpreventDefault()to keep it open.- focusOutside
[event: FocusOutsideEvent]Fires when focus moves outside. CallpreventDefault()to keep it open.- interactOutside
[event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on any press or focus outside. The tour ignores it and stays open.- openAutoFocus
[event: Event]Fires when the popover opens. Focus goes to TourNext when there is one; call preventDefault() to keep focus where it is.- closeAutoFocus
[event: Event]Fires when the tour ends. Focus returns to the element that started it.
Slots
- default
{}TourTitle, TourDescription, TourFooter and TourClose.
Slots
- default
{}The step's heading. It names the popover.
Slots
- default
{}The step's text. It describes the popover.
Slots
- default
{}TourProgress first, then the buttons, pushed to the end.
Slots
- default
{ index: number; total: number; }The step count, "2 / 5" by default. Receivesindex, from 0, andtotal.
Props
- variant
"outline" "outline" | "solid" | "soft" | "subtle" | "ghost" | "link" | nullThe button's variant,outlineby default.- color
"neutral" ButtonColor | (string & {})The button's colour,neutralby default.- size
"sm" ButtonSizeThe button's size,smby default.
Slots
- default
{}The label, "Back" by default. Pressing it goes to the previous step; on the first step it is aria-disabled.
Props
- variant
"solid" "solid" | "soft" | "subtle" | "outline" | "ghost" | "link" | nullThe button's variant,solidby default.- color
"primary" ButtonColor | (string & {})The button's colour,primaryby default.- size
"sm" ButtonSizeThe button's size,smby default.
Slots
- default
{ hasNext: boolean; }The label, "Next", or "Finish" on the last step of a tour that does not loop. ReceiveshasNext. Pressing it goes on, back to the first step when the tour loops, or finishes the tour.
Slots
- default
{}The icon, an X by default. Pressing it ends the tour.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| tour-content | data-state, data-side, data-align, data-centered | The popover. data-centered is set while the step has no element to point at. |
| tour-title | — | The step's heading, which names the popover. |
| tour-description | — | The step's text, which describes the popover. |
| tour-footer | — | The row of progress and buttons. |
| tour-progress | — | The step count. |
| tour-previous | aria-disabled | Back, disabled on the first step. |
| tour-next | — | Next, or Finish on the last step. |
| tour-close | — | Ends the tour. |
Accessibility
| Key | Action |
|---|---|
| Escape | Ends the tour. |
| Tab | Moves between the buttons in the popover, then on to the page. |
The popover is labelled by TourTitle and described by TourDescription. Back stays focusable on the first step and says it is disabled, so going back to the start does not drop focus. Buttons read "Back", "Next", "Finish" and "Close": pass your own text in their slots, and an aria-label on TourClose, to translate them.