Skip to content

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
basic-tour.svelte
<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
placement.svelte
<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
non-modal-mask-false.svelte
<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
custom-gap.svelte
<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
controlled-state.svelte
<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

NameTypeDefaultDescription
stepsrequiredTourStepDef[]—Array of step definitions.
openbindablebooleanfalseWhether the tour is visible. Bindable.
currentbindablenumber0Active step index. Bindable.
onClose() => void—Called when the tour is dismissed.
onChange(current: number) => void—Called when the step changes.
maskbooleantrueShow 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.
arrowbooleantrueShow arrow pointing from card to target.
placementTourPlacement'bottom'Default placement for all steps.
zIndexnumber350z-index of the tour overlay layer.
scrollIntoViewOptionsboolean | ScrollIntoViewOptionstrueScroll targets into view before showing.
disabledInteractionbooleanfalseBlock interaction with highlighted element.
indicatorsRenderSnippet<[current: number, total: number]>—Custom step indicator renderer.

TourStepDef

From phoundry-ui@0.4.21

NameTypeDefaultDescription
target(() => HTMLElement | null) | undefined—Element to highlight. Omit for center-screen placement.
titlestring | undefined—Step title.
descriptionstring | undefined—Step description text.
coverSnippet<[]> | undefined—Cover content (image/video) above the title.
placementTourPlacement | undefined—Override placement for this step.
maskboolean | undefined—Override global mask setting for this step.
scrollIntoViewboolean | ScrollIntoViewOptions | undefined—Override scroll behavior for this step.
nextButtonTextstring | undefined—Custom "Next" / "Finish" button label.
prevButtonTextstring | undefined—Custom "Previous" button label.

Usage tips

  • Use bind:open and bind:current to control the tour externally.
  • Each step’s target is a function returning an HTMLElement - use bind:element on buttons or document.getElementById.
  • Omitting target (or returning null) centers the card on screen - useful for intro/welcome steps.
  • Set mask=false with type="primary" for a non-modal tour that doesn’t block interaction.
  • The gap prop controls the highlight cutout padding (offset) and corner rounding (radius) around the target.
  • Keyboard: Escape closes, ArrowLeft/ArrowRight navigate steps.
  • Set disabledInteraction when you want the highlighted control read-only while still visually emphasizing it.
  • Turn off arrow for dense layouts where the pointer would collide with nearby UI; combine with type="primary" for contrast.
  • Raise zIndex if 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.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.