Tour
A multi-step guided tour overlay that highlights target elements and displays positioned popover cards with navigation controls.
import { Tour } from "phoundry-ui";import type { TourStepDef } from "phoundry-ui";Basic Tour
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { Tour } from "phoundry-ui"; import type { TourStepDef } from "phoundry-ui";
let basicOpen = $state(false);
let basicRef1: HTMLButtonElement | undefined = $state();
let basicRef2: HTMLButtonElement | undefined = $state();
let basicRef3: HTMLButtonElement | undefined = $state();
const basicSteps: TourStepDef[] = $derived([ { target: () => basicRef1 as HTMLElement, title: "Upload File", description: "Click here to upload a file to the system.", placement: "bottom", }, { target: () => basicRef2 as HTMLElement, title: "Save Changes", description: "Save your current progress before continuing.", placement: "bottom", }, { target: () => basicRef3 as HTMLElement, title: "More Options", description: "Access additional settings and preferences from here.", placement: "bottom-end", }, ]);</script>
<div class="flex items-center gap-2"> <Button bind:element={basicRef1}>Upload</Button> <Button bind:element={basicRef2}>Save</Button> <Button bind:element={basicRef3} variant="outline">More</Button> <Button variant="primary" onclick={() => (basicOpen = true)} >Begin Tour</Button ></div><Tour bind:open={basicOpen} steps={basicSteps} />Placement
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { Tour } from "phoundry-ui"; import type { TourStepDef } from "phoundry-ui";
let placementOpen = $state(false);
let placeRef: HTMLButtonElement | undefined = $state();
let placementValue: TourStepDef["placement"] = $state("bottom");
const placementOptions: TourStepDef["placement"][] = [ "top", "top-start", "top-end", "bottom", "bottom-start", "bottom-end", "left", "left-start", "left-end", "right", "right-start", "right-end", "center", ];
const placementSteps: TourStepDef[] = $derived([ { target: () => placeRef as HTMLElement, title: `Placement: ${placementValue}`, description: "The card is positioned relative to this element using the selected placement.", placement: placementValue, }, ]);</script>
<div class="mb-3 flex flex-wrap items-center gap-2"> {#each placementOptions as p (p)} <Button size="sm" variant={placementValue === p ? "primary" : "outline"} onclick={() => { placementValue = p; }} > {p} </Button> {/each}</div><div class="flex justify-center py-6"> <Button bind:element={placeRef} variant="primary" onclick={() => (placementOpen = true)} > Show Tour ({placementValue}) </Button></div><Tour bind:open={placementOpen} steps={placementSteps} />Non-modal (mask=false)
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { Tour } from "phoundry-ui"; import type { TourStepDef } from "phoundry-ui";
let nonModalOpen = $state(false);
let nmRef1: HTMLButtonElement | undefined = $state();
let nmRef2: HTMLButtonElement | undefined = $state();
const nonModalSteps: TourStepDef[] = $derived([ { target: () => nmRef1 as HTMLElement, title: "Non-modal Step 1", description: "No mask overlay-. The page stays interactive.", }, { target: () => nmRef2 as HTMLElement, title: "Non-modal Step 2", description: 'Using type="primary" helps the card stand out without a mask.', }, ]);</script>
<div class="flex items-center gap-2"> <Button bind:element={nmRef1}>Upload</Button> <Button bind:element={nmRef2}>Save</Button> <Button variant="primary" onclick={() => (nonModalOpen = true)} >Begin Non-modal Tour</Button ></div><Tour bind:open={nonModalOpen} mask={false} type="primary" steps={nonModalSteps}/>Custom Gap
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { Tour } from "phoundry-ui"; import type { TourStepDef } from "phoundry-ui";
let gapOpen = $state(false);
let gapRef: HTMLButtonElement | undefined = $state();
let gapOffset = $state(12);
let gapRadius = $state(8);
const gapSteps: TourStepDef[] = $derived([ { target: () => gapRef as HTMLElement, title: "Custom Gap", description: `offset: ${gapOffset}px, radius: ${gapRadius}px`, }, ]);</script>
<div class="flex items-center gap-4"> <label class="flex items-center gap-2 text-xs text-txt-secondary"> Offset: <input type="range" min="0" max="24" bind:value={gapOffset} class="w-24" /> <span class="w-6 font-mono">{gapOffset}</span> </label> <label class="flex items-center gap-2 text-xs text-txt-secondary"> Radius: <input type="range" min="0" max="20" bind:value={gapRadius} class="w-24" /> <span class="w-6 font-mono">{gapRadius}</span> </label> <Button bind:element={gapRef} variant="primary" onclick={() => (gapOpen = true)}>Show Tour</Button ></div><Tour bind:open={gapOpen} gap={{ offset: gapOffset, radius: gapRadius }} steps={gapSteps}/>Controlled State
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { Tour } from "phoundry-ui"; import type { TourStepDef } from "phoundry-ui";
let controlledOpen = $state(false);
let controlledStep = $state(0);
let ctrlRef1: HTMLButtonElement | undefined = $state();
let ctrlRef2: HTMLButtonElement | undefined = $state();
let ctrlRef3: HTMLButtonElement | undefined = $state();
const controlledSteps: TourStepDef[] = $derived([ { target: () => ctrlRef1 as HTMLElement, title: "Step 1", description: "First step.", }, { target: () => ctrlRef2 as HTMLElement, title: "Step 2", description: "Second step.", }, { target: () => ctrlRef3 as HTMLElement, title: "Step 3", description: "Third step.", }, ]);</script>
<div class="flex items-center gap-2"> <Button bind:element={ctrlRef1}>A</Button> <Button bind:element={ctrlRef2}>B</Button> <Button bind:element={ctrlRef3}>C</Button> <Button variant="outline" onclick={() => { controlledStep = 0; controlledOpen = true; }} > Start at 1 </Button> <Button variant="outline" onclick={() => { controlledStep = 1; controlledOpen = true; }} > Jump to 2 </Button> <Button variant="primary" onclick={() => { controlledStep = 2; controlledOpen = true; }} > Jump to 3 </Button> <span class="text-xs text-txt-tertiary">Step: {controlledStep}</span></div><Tour bind:open={controlledOpen} bind:current={controlledStep} steps={controlledSteps}/>Tour Props
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
stepsrequired | TourStepDef[] | — | Array of step definitions. |
openbindable | boolean | false | Whether the tour is visible. Bindable. |
currentbindable | number | 0 | Active step index. Bindable. |
onClose | () => void | — | Called when the tour is dismissed. |
onChange | (current: number) => void | — | Called when the step changes. |
mask | boolean | true | Show dimmed mask overlay with target cutout. |
type | "primary" | "default" | 'default' | Card color scheme. |
gap | { offset?: number | undefined; radius?: number | undefined; } | {} | Highlight area gap around the target element. |
arrow | boolean | true | Show arrow pointing from card to target. |
placement | TourPlacement | 'bottom' | Default placement for all steps. |
zIndex | number | 350 | z-index of the tour overlay layer. |
scrollIntoViewOptions | boolean | ScrollIntoViewOptions | true | Scroll targets into view before showing. |
disabledInteraction | boolean | false | Block interaction with highlighted element. |
indicatorsRender | Snippet<[current: number, total: number]> | — | Custom step indicator renderer. |
TourStepDef
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
target | (() => HTMLElement | null) | undefined | — | Element to highlight. Omit for center-screen placement. |
title | string | undefined | — | Step title. |
description | string | undefined | — | Step description text. |
cover | Snippet<[]> | undefined | — | Cover content (image/video) above the title. |
placement | TourPlacement | undefined | — | Override placement for this step. |
mask | boolean | undefined | — | Override global mask setting for this step. |
scrollIntoView | boolean | ScrollIntoViewOptions | undefined | — | Override scroll behavior for this step. |
nextButtonText | string | undefined | — | Custom "Next" / "Finish" button label. |
prevButtonText | string | undefined | — | Custom "Previous" button label. |
Usage tips
- Use
bind:openandbind:currentto control the tour externally. - Each step’s
targetis a function returning anHTMLElement- usebind:elementon buttons ordocument.getElementById. - Omitting
target(or returning null) centers the card on screen - useful for intro/welcome steps. - Set
mask=falsewithtype="primary"for a non-modal tour that doesn’t block interaction. - The
gapprop controls the highlight cutout padding (offset) and corner rounding (radius) around the target. - Keyboard:
Escapecloses,ArrowLeft/ArrowRightnavigate steps. - Set
disabledInteractionwhen you want the highlighted control read-only while still visually emphasizing it. - Turn off
arrowfor dense layouts where the pointer would collide with nearby UI; combine withtype="primary"for contrast. - Raise
zIndexif other overlays (command palette, modal) share the same stacking context and occlude the tour.
CSS styling
.ph-tour is the stable identification hook for Tour. Part selectors and --_ph-* properties are internal. Component CSS is scoped and unlayered; Consumer classes remain additive and utility overrides may lose precedence.
Tour panel, arrow, and mask motion are component-owned. data-variant selects default or primary chrome. Target measurements and step callbacks are unchanged.
Keep the shared component stylesheet and a named Theme imported. Decorative motion respects reduced-motion preferences.
Target scrolling is immediate under reduced motion, including steps with scroll-into-view options.