Tour

new

Let me show you around. A popover that walks from one element to the next, driven by useTour.

Demo
EK

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 no target, 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.

OptionDescription
initialStepThe step start() opens on. 0 by default.
loopGo back to the first step after the last instead of finishing.
scrollIntoViewfalse 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.

With dots
  1. Plan
  2. Team
  3. Repository

API Reference

class is also accepted on every part except Tour and merged over its classes.

Data attributes

data-slotAttributesDescription
tour-contentdata-state, data-side, data-align, data-centeredThe 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-previousaria-disabledBack, disabled on the first step.
tour-next—Next, or Finish on the last step.
tour-close—Ends the tour.

Accessibility

KeyAction
EscapeEnds the tour.
TabMoves 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.

Changelog

  1. registry 0.24.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  2. core 0.17.1

    35a5371 — No component styles an element through a :has() on its parent or group any more. Chrome restyles the whole subtree of every :has() anchor above a node that is added or removed, once some rule puts :has() away from the element it styles: a page wrapped in one such anchor recalculated every element for each list row it mounted. The Dialog, Drawer and Tour headers, the InputGroup and InputNumber insets, the Combobox clear button, the InputFloating notch, a FieldLabel beside a disabled checkbox or radio, the Rating ring, and the Slider and ScrollArea examples now read their neighbours with ~ or a :has() on the element itself. The InputGroup addons fade through a variable that the group sets. FileUpload, Image, Marquee and DataTable mark the state on an element instead: the hidden input's focus, an ImageError inside, keyboard focus, and the body above pinned bottom rows. scripts/has-selectors.test.ts keeps the pattern out.

    useSwipeSnap no longer flushes styles for an instant move that leaves the offset where it is, such as new points at rest.

  3. registry 0.22.0

    49f6278 — useTour returns loop, and TourNext reads "Next" rather than "Finish" on the last step of a looping tour, where pressing it goes back to the first step.

    0a937be — TourContent honours a listener that calls preventDefault() on openAutoFocus: focus stays where it is instead of moving to TourNext.

    01c825f — A Tour whose tour starts during setup renders on the server: it no longer reads document.activeElement there to remember the element to give focus back to.

  4. core 0.16.0

    6b26bf7 — useTour follows the page while a tour is open: a string target that mounts after its step opened (a route or a v-if section) anchors the panel once it appears, and a target removed mid-step centres the panel instead of pinning it to the viewport's top-left corner.

    49f6278 — useTour returns loop, and TourNext reads "Next" rather than "Finish" on the last step of a looping tour, where pressing it goes back to the first step.

  5. core 0.15.1

    32546e6 — useTour: reference keeps the current step's target after the tour closes instead of turning undefined, so the popover's exit animation plays where it was rather than jumping to the top-left corner.

  6. registry 0.18.0

    779955e — Corners come in three roles: rounded-control-*, rounded-surface-* and rounded-item-*, each scaled from --radius and tunable on its own with --control-radius, --surface-radius and --item-radius, on :root or any element. Every component uses them, and cn() merges them, so a class prop still wins.

    - --control-radius was the Input family's frame variable. It now sets every control, and the frames use --frame-radius. - Nested parts no longer turn square at small radii: the InputGroup button, the InputNumber steppers, the TagsInput chips, the DatePicker trigger and the Toast and Tour close buttons. - Menus, lists, pill tabs, the menubar and the toolbar wrap their corners around their items. Pill tabs are rounder (12/8px at md instead of 8/4px), menus and lists grow by up to 2px, and their rows at sizes xs and xl follow their height. Item sm takes 8px instead of 6.4px.

  7. registry 0.17.0

    7951a0f — New Marker: an inline status, a bordered row or a labelled separator, from shadcn-vue, with a color. New Banner: a full-width notice with a title, a subtitle, actions and a close button, v-model:open and color. New Tour: parts over Popover for a guided tour driven by useTour. Skeleton takes a color.

  8. core 0.13.0

    7951a0f — New shimmer utilities in @kappa-ui/core/tailwind.css, ported from shadcn-vue: a highlight that sweeps across text drawn with background-clip: text, with shimmer-once, shimmer-reverse, shimmer-none and shimmer-color-*, shimmer-duration-*, shimmer-spread-*, shimmer-angle-*. New @kappa-ui/core/tour with useTour, ported from Nuxt UI: the state of a guided tour whose reference a popover anchor follows; a step without a target, or whose target matches nothing, sits in the centre of the viewport and sets centered. animate-skeleton-wave draws its band in the element's tone when the element has a data-color.