Tour

A component for guiding users through a series of steps or features in an application or website.

Anatomy

Usage

<script>
  import {Tour, type TourStepDetails} from 'ui-ingredients';
  import {XCloseIcon} from '$lib/icons';

  let steps: TourStepDetails[] = [
    {
      type: 'tooltip',
      arrow: true,
      title: 'Step 1 Title',
      description: 'Step 1 Description',
      actions,
      target() {
        return document.getElementById('target-1');
      },
    },
    {
      type: 'tooltip',
      arrow: true,
      title: 'Step 2 Title',
      description: 'Step 2 Description',
      actions,
      target() {
        return document.getElementById('target-2');
      },
    },
    {
      type: 'tooltip',
      arrow: true,
      title: 'Step 3 Title',
      description: 'Step 3 Description',
      actions,
      target() {
        return document.getElementById('target-3');
      },
    },
  ];
</script>

<Tour.Root {steps}>
  {#snippet children(ctx)}
    {@const actions = ctx.step?.actions ?? []}

    <Tour.Trigger>Start</Tour.Trigger>
    <Tour.Backdrop />
    <Tour.Spotlight />
    <Tour.Positioner>
      <Tour.Content>
        <Tour.Arrow>
          <Tour.ArrowTip />
        </Tour.Arrow>

        <Tour.ProgressText />
        <Tour.Title />
        <Tour.Description />

        {#each actions as action}
          <Tour.ActionTrigger {action} />
        {/each}

        <Tour.CloseTrigger>
          <XCloseIcon />
        </Tour.CloseTrigger>
      </Tour.Content>
    </Tour.Positioner>
  {/snippet}
</Tour.Root>

<div id="target-1">Target 1</div>
<div id="target-2">Target 2</div>
<div id="target-3">Target 3</div>

API Reference

Root

Prop	Default	Description
`animateOnMount`	`true`	`boolean` Whether to run the enter animation when the component mounts.
`closeOnEscape`	`true`	`boolean` Whether to close the tour when the user presses the escape key
`closeOnInteractOutside`	`true`	`boolean` Whether to close the tour when the user clicks outside the tour
`id`		`string` The unique identifier of the machine.
`ids`		`{ content?: string; title?: string; description?: string; positioner?: string; backdrop?: string; arrow: string; }` The ids of the elements in the tour. Useful for composition.
`keepMounted`	`true`	`boolean` Whether to keep the component mounted after exit.
`keyboardNavigation`	`true`	`boolean` Whether to allow keyboard navigation (right/left arrow keys to navigate between steps)
`lazyMount`	`false`	`boolean` Whether to enable lazy mounting.
`onExitComplete`		`() => void` Callback that fires when the exit animation of the dialog completes.
`onFocusOutside`		`(event: FocusOutsideEvent) => void` Function called when the focus is moved outside the component
`onInteractOutside`		`(event: InteractOutsideEvent) => void` Function called when an interaction happens outside the component
`onPointerDownOutside`		`(event: PointerDownOutsideEvent) => void` Function called when the pointer is pressed down outside the component
`onStatusChange`		`(details: StatusChangeDetails) => void` Callback when the tour is opened or closed
`onStepChange`		`(details: StepChangeDetails) => void` Callback when the highlighted step changes
`onStepsChange`		`(details: StepsChangeDetails) => void` Callback when the steps change
`preventInteraction`	`false`	`boolean` Prevents interaction with the rest of the page while the tour is open
`spotlightOffset`	`{ x: 10, y: 10, }`	`Point` The offsets to apply to the spotlight
`spotlightRadius`	`4`	`number` The radius of the spotlight clip path
`stepId`		`string` The id of the currently highlighted step
`steps`		`StepDetails[]` The steps of the tour
`translations`		`IntlTranslations` The translations for the tour

ActionTrigger

Prop	Default	Description
`action`		`StepAction`
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	action-trigger
`data-scope`	tour
`data-type`	The type of the item

Arrow

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

ArrowTip

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Backdrop

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	backdrop
`data-scope`	tour
`data-state`	"open" \| "closed"
`data-type`	The type of the item

CloseTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	close-trigger
`data-scope`	tour
`data-type`	The type of the item

Content

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-has-nested`	popover
`data-nested`	popover
`data-part`	content
`data-placement`	The placement of the content
`data-scope`	tour
`data-state`	"open" \| "closed"
`data-step`
`data-type`	The type of the item

Description

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	description
`data-placement`	The placement of the description
`data-scope`	tour

Positioner

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	positioner
`data-placement`	The placement of the positioner
`data-scope`	tour
`data-type`	The type of the item

ProgressText

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Spotlight

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Title

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	title
`data-placement`	The placement of the title
`data-scope`	tour

Trigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Accessibility

Keyboard Support

Key	Description
ArrowRight	Moves to the next step in the tour.
ArrowLeft	Moves to the previous step in the tour.
Esc	Closes the tour.