Tour
Composable guided walkthroughs with anchored content and a target spotlight.
Quick Preview
Find a place that fits
Explore homes selected for your preferences.
Usage
Import the parts from @giddaa-housing/ui/tour. Keep targets and step content in your app. TourContent accepts a ref to an existing element; useTour() exposes the zero-based step so you can change the anchor and content together.
import { useRef } from "react";
import { Button } from "@giddaa-housing/ui/button";
import {
Tour, TourTrigger, TourContent, TourHeader, TourTitle,
TourDescription, TourSkip, TourFooter, TourIndicators,
TourNavigation, TourPrevious, TourNext, useTour,
} from "@giddaa-housing/ui/tour";
function Steps() {
const search = useRef<HTMLButtonElement>(null);
const saved = useRef<HTMLButtonElement>(null);
const { step } = useTour();
return (
<>
<Button ref={search}>Search</Button>
<Button ref={saved}>Saved homes</Button>
<TourTrigger render={<Button />}>Show me around</TourTrigger>
<TourContent anchor={step === 0 ? search : saved}>
<TourHeader>
<TourTitle>{step === 0 ? "Find your home" : "Keep your favourites"}</TourTitle>
<TourSkip />
</TourHeader>
<TourDescription>
{step === 0 ? "Search by location and budget." : "Your saved homes live here."}
</TourDescription>
<TourFooter>
<TourIndicators />
<TourNavigation>
{step > 0 && <TourPrevious />}
<TourNext />
</TourNavigation>
</TourFooter>
</TourContent>
</>
);
}
export function HomeTour() {
return <Tour stepCount={2}><Steps /></Tour>;
}Examples
Text and icon navigation
The final Next button becomes “Got it” and closes the tour. Back is disabled on the first step; omit it there to match the design. Skip, title, and indicators are optional compositions. When omitting the title, give TourContent an aria-label.
Find a place that fits
Explore homes selected for your preferences.
Icon-only navigation
Pass iconOnly to either navigation button. Accessible labels remain present, including “Finish tour” on the last step. Override labels with aria-label for localization.
Find a place that fits
Explore homes selected for your preferences.
Controlled state
Use open / onOpenChange and step / onStepChange to coordinate application state. onComplete runs only when the final Next is pressed; onSkip runs only for Skip. Escape closes without reporting completion. Reopening preserves the step by default; reset controlled step to 0 on opening to restart, as the previews do. Persist completion in the consuming app if a tour should run only once.
Props
| Part / prop | Type | Default | Description |
|---|---|---|---|
Tour.stepCount | number | required | Positive integer number of steps. |
Tour.open / defaultOpen | boolean | false | Controlled / initial visibility. |
Tour.step / defaultStep | number | 0 | Controlled / initial zero-based step. |
Tour.onOpenChange | (open: boolean) => void | — | Visibility changes, including Escape. |
Tour.onStepChange | (step: number) => void | — | Back / Next step changes. |
Tour.onComplete / onSkip | () => void | — | Distinct completion and skip events. |
TourContent.anchor | RefObject<HTMLElement | null> | required | Mounted target element for the current step. |
TourContent.side / align | Base UI positioner props | bottom / start | Collision-aware placement. |
TourContent.sideOffset / alignOffset | number | 12 / 0 | Distance and alignment adjustment. |
TourContent.showArrow | boolean | true | Pointer toward the target. |
TourContent.spotlight | boolean | true | Dim the page around the target. |
TourContent.spotlightPadding | number | 4 | Target highlight padding in pixels. |
TourContent.initialFocus / finalFocus | Base UI popup props | Base UI defaults | Customize opening and return focus. |
TourPrevious.iconOnly / TourNext.iconOnly | boolean | false | Chevron-only navigation. |
TourPrevious / TourNext / TourSkip | Button props | — | Custom labels, variants, sizes, and cancellable click handlers. |
| Layout parts | Native div props | — | Header, footer, navigation, indicators. |
useTour() | { open, step, stepCount, setStep, next, skip, close } | — | Compose custom step content and controls. |
Accessibility
- The modal popover manages focus, Escape, and focus restoration. Background targets are highlighted for explanation; interaction stays within the tour until it closes.
- Title and description label the dialog. Supply
aria-labelwhen no title is rendered. - A live region announces step progress. Icon-only controls include accessible names; a keyboard-accessible Close remains available even without Skip.
- Back cannot move before the first step; Next completes at the last step. Clicking the background does not dismiss the tour.
- Targets should be mounted and visible before opening or advancing. Each step scrolls its target into view without animation; positioning and the spotlight follow scrolling, resizing, and layout changes.
- Surface, typography, borders, actions, and indicators use the shared semantic theme tokens. No motion is required to understand navigation.