Skip to content

Overview

<x-aura-filament::tour> drops a guided tour into any Filament page or Livewire view. It relies on Alpine only — no Shepherd, no Driver.js, no Intro.js, no extra bundle.

The tour:

  • Spotlights the target element with a primary-lit outline and a box-shadow: 0 0 0 9999px rgba(…) backdrop trick (no clipping math, works on any layout).
  • Floats a tooltip with the step's title + description and Back / Next / Skip / Finish buttons. Placement is a hint — if the preferred side overflows, the tooltip flips to whichever side fits.
  • Persists "seen" state in localStorage, so a returning user isn't pestered.
  • Scrolls the target smoothly into view on each step.
  • Supports external triggers — dispatch aura-tour:start or aura-tour:reset from any button anywhere.

Minimal example

@php
    use BlueStarSystem\AuraFilament\Support\TourStep;
@endphp

<x-filament-panels::page>
    {{-- ... your page content ... --}}

    <x-aura-filament::tour
        id="dashboard-tour"
        :steps="[
            TourStep::make()
                ->title('Welcome!')
                ->description('A quick 3-step tour of the dashboard.'),
            TourStep::make('#sidebar')
                ->title('Navigation')
                ->description('All your panels live here.')
                ->placement('right'),
            TourStep::make('[data-stats-widget]')
                ->title('Stats')
                ->description('At-a-glance metrics. Refresh live.')
                ->placement('bottom'),
        ]"
    />
</x-filament-panels::page>

A TourStep::make() with no selector is rendered as a centered welcome/exit modal (no spotlight). Useful for the first and last steps of a tour.

TourStep API

TourStep::make(?string $selector = null)
    ->title(string $title)
    ->description(?string $description)
    ->placement('top' | 'bottom' | 'left' | 'right');   // default: bottom
  • selector — any valid CSS selector (#id, .class, [data-*]). The driver calls document.querySelector() — first match wins.
  • placement is a hint. If the target would push the tooltip off-screen, the driver tries the other three sides and picks the first that fits. Unknown placement values fall back to bottom.

Component attributes

<x-aura-filament::tour
    id="my-tour"
    :steps="$steps"
    :auto-start="true"

    back-label="Previous"
    next-label="Continue"
    finish-label="Done"
    skip-label="Not now"
/>
  • id — used as the localStorage key (aura-tour:{id}:seen). Use distinct IDs if a panel has multiple tours.
  • auto-start — if true, the tour runs 400ms after the page loads, but only if the user hasn't already dismissed it.
  • Labels are fully translatable — pass __('my.tour.next') etc.

Triggering from anywhere

<button
    type="button"
    x-on:click="window.dispatchEvent(new CustomEvent('aura-tour:start', {detail:{id:'my-tour'}}))"
>
    Take the tour
</button>

Dispatch aura-tour:start to force-start (bypassing the "already seen" check). Dispatch aura-tour:reset to clear the localStorage flag so the next page load triggers the tour again.

Omit detail.id to trigger every tour currently on the page.

Styling

All color tokens use var(--primary-*) directly (or color-mix(in oklab, …) for alpha tints) — the Filament theme configurator re-tints the tour live, without a reload.

If you want to change the backdrop darkness, target:

.fi-aura-tour-backdrop {
    box-shadow: 0 0 0 9999px rgba(9, 12, 24, 0.75);
}

The outline color animates between --primary-500 and --primary-400 every 2.2s for a gentle "look here" effect. Disable with prefers-reduced-motion: reduce (automatic, no config needed).

Live showcase

A 5-step tour runs on demo.aura-ui.com/admin/components-showcase — click "Take the tour" in the banner.