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 / propTypeDefaultDescription
Tour.stepCountnumberrequiredPositive integer number of steps.
Tour.open / defaultOpenbooleanfalseControlled / initial visibility.
Tour.step / defaultStepnumber0Controlled / 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.anchorRefObject<HTMLElement | null>requiredMounted target element for the current step.
TourContent.side / alignBase UI positioner propsbottom / startCollision-aware placement.
TourContent.sideOffset / alignOffsetnumber12 / 0Distance and alignment adjustment.
TourContent.showArrowbooleantruePointer toward the target.
TourContent.spotlightbooleantrueDim the page around the target.
TourContent.spotlightPaddingnumber4Target highlight padding in pixels.
TourContent.initialFocus / finalFocusBase UI popup propsBase UI defaultsCustomize opening and return focus.
TourPrevious.iconOnly / TourNext.iconOnlybooleanfalseChevron-only navigation.
TourPrevious / TourNext / TourSkipButton props—Custom labels, variants, sizes, and cancellable click handlers.
Layout partsNative 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-label when 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.

On this page