PHPackages                             yacoubalhaidari/filament-tour - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Admin Panels](/categories/admin)
4. /
5. yacoubalhaidari/filament-tour

ActiveLibrary[Admin Panels](/categories/admin)

yacoubalhaidari/filament-tour
=============================

An interactive guided tour for Filament Admin Panel using Shepherd.js

v1.0.3(1mo ago)142.3k↓56.9%5MITPHPPHP ^8.2

Since Jan 1Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/YacoubAl-hardari/filament-tour)[ Packagist](https://packagist.org/packages/yacoubalhaidari/filament-tour)[ Docs](https://github.com/yacoubalhaidari/filament-tour)[ RSS](/packages/yacoubalhaidari-filament-tour/feed)WikiDiscussions master Synced 3d ago

READMEChangelogDependencies (16)Versions (5)Used By (0)

[![Gemini_Generated_Image_xwwnlrxwwnlrxwwn](https://private-user-images.githubusercontent.com/94101869/531345759-f9b79e27-5051-4a70-a295-50f450a94c4d.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODMwMDA5MDEsIm5iZiI6MTc4MzAwMDYwMSwicGF0aCI6Ii85NDEwMTg2OS81MzEzNDU3NTktZjliNzllMjctNTA1MS00YTcwLWEyOTUtNTBmNDUwYTk0YzRkLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA3MDIlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNzAyVDEzNTY0MVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTk5N2IwZGJjOGYyMWIyNWFhODJiOTY4MTg2NzUwYmE2ZWY3YjljOGRjZDhmMDQyODg2MTZkOTk4MWY0YzAwZGMmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JnJlc3BvbnNlLWNvbnRlbnQtdHlwZT1pbWFnZSUyRnBuZyJ9.sDHC09qYvzHApK1kmqbhfIuHNhH6lWSM8_-V1iRkI9A)](https://private-user-images.githubusercontent.com/94101869/531345759-f9b79e27-5051-4a70-a295-50f450a94c4d.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODMwMDA5MDEsIm5iZiI6MTc4MzAwMDYwMSwicGF0aCI6Ii85NDEwMTg2OS81MzEzNDU3NTktZjliNzllMjctNTA1MS00YTcwLWEyOTUtNTBmNDUwYTk0YzRkLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA3MDIlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNzAyVDEzNTY0MVomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTk5N2IwZGJjOGYyMWIyNWFhODJiOTY4MTg2NzUwYmE2ZWY3YjljOGRjZDhmMDQyODg2MTZkOTk4MWY0YzAwZGMmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JnJlc3BvbnNlLWNvbnRlbnQtdHlwZT1pbWFnZSUyRnBuZyJ9.sDHC09qYvzHApK1kmqbhfIuHNhH6lWSM8_-V1iRkI9A)Filament Tour
-------------

[](#filament-tour)

An interactive guided tour for the Filament admin panel powered by Shepherd.js.

This plugin adds a tour trigger button to the Filament user menu and lets you build a step‑by‑step walkthrough of your panel pages, with full control over colors, texts, and welcome/finish screens.

**Features:** Resources & custom pages · Livewire SPA navigation · Sidebar highlight + modal overlay · Custom welcome/finish · Progress resume · EN / AR / ID translations

Contents
--------

[](#contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Registering the Plugin](#registering-the-plugin)
- [Defining Dynamic Tour Steps](#defining-dynamic-tour-steps)
- [How Navigation Matching Works](#how-navigation-matching-works)
- [Localization](#localization-en--ar--id)
- [Running the Tour](#running-the-tour)
- [Building Frontend Assets](#building-frontend-assets-package-contributors)
- [Troubleshooting](#troubleshooting)

🎥 Filament Tour – Video Demo
----------------------------

[](#-filament-tour--video-demo)

[![Filament Tour – Video Demo](https://camo.githubusercontent.com/9a75eb6a97aa11e9acdb004fb7b740585a6a8d40a2bc5f0bb54085eb6aa00e67/68747470733a2f2f696d672e796f75747562652e636f6d2f76692f54336e434f59636c33446f2f6d617872657364656661756c742e6a7067)](https://www.youtube.com/watch?v=T3nCOYcl3Do)

> Click the image to watch the full video on YouTube.

---

Requirements
------------

[](#requirements)

- PHP ^8.2
- Filament ^3.0 or ^4.0

---

Installation
------------

[](#installation)

Require the package via Composer:

```
composer require yacoubalhaidari/filament-tour
```

Optionally publish the CSS/JS assets into your `public` directory (recommended in production so browsers load a stable copy):

```
php artisan filament-tour:assets
# or
php artisan filament:assets
```

This publishes:

- `public/css/yacoubalhaidari/filament-tour/filament-tour-styles.css`
- `public/js/yacoubalhaidari/filament-tour/filament-tour-scripts.js`

> The service provider auto‑registers assets from the package (`resources/dist/filament-tour.js`, falling back to `resources/js/shepherd-tour.js`). After upgrading the package, run `php artisan filament:assets` and hard‑refresh the browser (`Ctrl+Shift+R`).

---

Registering the Plugin
----------------------

[](#registering-the-plugin)

In your Filament `PanelProvider`, register the plugin and optionally customize the tour button and appearance.

```
use Filament\Panel;
use YacoubAlhaidari\FilamentTour\FilamentTourPlugin;

class AdminPanelProvider extends PanelProvider
{
	public function panel(Panel $panel): Panel
	{
		return $panel
			->plugins([
				FilamentTourPlugin::make()
					// Show / hide the trigger button in the user menu
					->showTourButton(true)

					// Trigger button appearance
					->tourButtonIcon('heroicon-o-academic-cap')
					->tourButtonColor('info')
					->tourButtonTooltip(trans('filament-tour.tooltip'))

					// Color customization (all are optional)
					->headerColor('linear-gradient(135deg, #282835 0%, #282835 100%)')
					->primaryButtonColor('linear-gradient(135deg, #282835 0%, #282835 100%)')
					->secondaryButtonColor('linear-gradient(135deg, #282835 0%, #282835 100%)')
					->textColor('#1f2937')
					->backgroundColor('linear-gradient(135deg, #282835 0%, #282835 100%)')
					->contentBackgroundColor('#282835')
					->footerBackgroundColor('linear-gradient(180deg, #282835 0%, #282835 100%)')
					->primaryButtonHoverColor('linear-gradient(135deg, #ea580c 0%, #dc2626 100%)')
					->secondaryButtonHoverColor('linear-gradient(135deg, #282835 0%, #282835 100%)')
					->primaryButtonTextColor('#ffffff')
					->secondaryButtonTextColor('#ffffff')
					->footerBorderColor('rgba(0, 0, 0, 0.1)')

					// Optional custom welcome & finish steps
					->welcomeStep([
						'id' => 'welcome',
						'title' => 'مرحباً مخصص!',
						'text' => 'رسالة ترحيب مخصصة',
						'buttons' => [
							['text' => 'تخطي', 'action' => 'cancel', 'secondary' => true],
							['text' => 'ابدأ', 'action' => 'next', 'secondary' => false],
						],
					])
					->finishStep([
						'id' => 'finish',
						'title' => 'تهانينا مخصص!',
						'text' => 'رسالة إنهاء مخصصة',
						'buttons' => [
							['text' => 'السابق', 'action' => 'back', 'secondary' => true],
							['text' => 'إنهاء', 'action' => 'complete', 'secondary' => false],
						],
					]),
			]);
	}
}
```

### Plugin Methods

[](#plugin-methods)

All configuration methods are chainable on `FilamentTourPlugin::make()`:

- `showTourButton(bool $condition = true)` – Show or hide the tour trigger icon in the user menu.
- `tourButtonIcon(string $icon)` – Heroicon or custom icon class for the trigger button.
- `tourButtonColor(string $color)` – Filament color name (e.g. `info`, `primary`, `success`).
- `tourButtonTooltip(string $tooltip)` – Tooltip text shown when hovering the trigger button.

Color customization (all optional – values are used directly as CSS values and wired into CSS variables):

- `headerColor(string $color)` – Header background (e.g. gradient or hex color).
- `primaryButtonColor(string $color)` – Primary button background.
- `secondaryButtonColor(string $color)` – Secondary button background.
- `textColor(string $color)` – Main text color inside the tour.
- `backgroundColor(string $color)` – Overall tour background.
- `contentBackgroundColor(string $color)` – Content area background.
- `footerBackgroundColor(string $color)` – Footer background (where buttons sit).
- `primaryButtonHoverColor(string $color)` – Primary button hover background.
- `secondaryButtonHoverColor(string $color)` – Secondary button hover background.
- `primaryButtonTextColor(string $color)` – Text color inside the primary button.
- `secondaryButtonTextColor(string $color)` – Text color inside the secondary button.
- `footerBorderColor(string $color)` – Border color above the footer.

Custom welcome / finish steps:

- `welcomeStep(array $step)` – Override the default first step.
- `finishStep(array $step)` – Override the default last step.

Each step array supports at least:

```
[
	'id' => 'welcome',               // Unique step ID
	'title' => 'عنوان الخطوة',       // Step title
	'text' => 'HTML', // Step body (HTML allowed)
	'buttons' => [
		['text' => 'تخطي', 'action' => 'cancel',   'secondary' => true],
		['text' => 'التالي', 'action' => 'next',   'secondary' => false],
		['text' => 'السابق', 'action' => 'back',   'secondary' => true],
		['text' => 'إنهاء', 'action' => 'complete','secondary' => false],
	],
]
```

Supported button actions: `back`, `next`, `cancel`, `complete`.

---

Defining Dynamic Tour Steps
---------------------------

[](#defining-dynamic-tour-steps)

Dynamic steps are collected automatically by `TourStepCollector` from:

- **Filament Resources** that use `HasTourSteps`
- **Filament Pages** (custom pages) that use `HasTourSteps`

Steps are sorted by `getTourStepSort()` (lower = earlier). The tour order is:

`welcomeStep` → dynamic steps → `finishStep`

### On Resources

[](#on-resources)

Add the trait to any resource you want to appear in the tour:

```
use Filament\Resources\Resource;
use YacoubAlhaidari\FilamentTour\Concerns\HasTourSteps;

class MerchantResource extends Resource
{
	use HasTourSteps;

	public static function getTourStepId(): ?string
	{
		return 'merchants-list';
	}

	public static function getTourStepTitle(): ?string
	{
		return 'إدارة التجار';
	}

	public static function getTourStepDescription(): ?string
	{
		return 'وصف موجز لما يمكن للمستخدم القيام به هنا.';
	}

	public static function getTourStepFeatures(): array
	{
		return [
			'إضافة تاجر جديد',
			'تعديل بيانات التاجر',
			'عرض حالة المحافظ والطلبات',
		];
	}

	public static function getTourStepPosition(): string
	{
		// Shepherd position: top|bottom|left|right|center ...
		return 'right';
	}

	public static function getTourStepSort(): int
	{
		// Lower numbers appear earlier in the tour
		return 10;
	}
}
```

### What the Trait Provides

[](#what-the-trait-provides)

`HasTourSteps` defines the following static methods (with sensible defaults):

- `getTourSteps(): array` – Low-level hook if you want to return fully custom step definitions (defaults to `[]`).
- `getTourStepId(): ?string` – Unique ID for the step (also used as `data-tour` value).
- `getTourStepTitle(): ?string` – Step title (defaults to `getModelLabel()` on resources, or `getNavigationLabel()` on pages).
- `getTourStepDescription(): ?string` – Short description paragraph.
- `getTourStepFeatures(): array` – Bullet list of features; rendered as a list in the tooltip.
- `getTourStepPosition(): string` – Tooltip position relative to the target (default `right`).
- `getTourStepSort(): int` – Sort order (lower = earlier in the tour; default `100`).
- `getTourSelector(): ?string` – Selector used to attach the step (defaults to `getTourStepId()`).
- `hasTourStep(): bool` – Whether the resource should participate in the tour.

The package collects these steps via `TourStepCollector` and passes them to the frontend as `window.dynamicTourSteps`.

For resources, the collector resolves the step URL with `Resource::getUrl('index')` so the tour can navigate to the list page when needed.

### On Custom Pages

[](#on-custom-pages)

Use the same trait on a Filament `Page` class (must be registered on the panel):

```
use Filament\Pages\Page;
use YacoubAlhaidari\FilamentTour\Concerns\HasTourSteps;

class SignBuilder extends Page
{
    use HasTourSteps;

    protected static ?string $navigationLabel = 'Sign Builder';

    public static function getTourStepId(): ?string
    {
        return 'sign-builder';
    }

    public static function getTourStepTitle(): ?string
    {
        return 'Sign Builder';
    }

    public static function getTourStepDescription(): ?string
    {
        return 'Place signature fields on your PDF documents.';
    }

    public static function getTourStepFeatures(): array
    {
        return [
            'Add signature fields',
            'Assign signers',
            'Navigate document pages',
        ];
    }

    public static function getTourStepSort(): int
    {
        return 40;
    }
}
```

For pages, the collector uses `Page::getUrl()` (no `index` route). `getTourStepTitle()` falls back to `getNavigationLabel()` when `getModelLabel()` is not available.

---

How Navigation Matching Works
-----------------------------

[](#how-navigation-matching-works)

The frontend tags sidebar items with `data-tour="{stepId}"` so Shepherd can highlight the correct menu entry.

### Matching strategy (in order)

[](#matching-strategy-in-order)

1. **URL path (recommended)** – Each dynamic step includes a `url`. Links in the sidebar (`.fi-sidebar-item-btn`) whose `href` pathname matches that URL receive `data-tour`.
2. **Navigation label (fallback)** – `TourStepCollector::getNavigationMap()` builds `{ stepId => navigationLabel }` from `getNavigationLabel()` on each resource/page. Sidebar text is matched against the label.

### While the tour runs

[](#while-the-tour-runs)

- **Shepherd modal overlay** – Darkens the panel and cuts a hole around the target element.
- **`.shepherd-target`** – Orange outline on the attached element (see `resources/css/shepherd-tour.css`).
- **`.shepherd-tour-active-nav`** – Extra highlight on the active sidebar item during the step.

### Livewire SPA navigation

[](#livewire-spa-navigation)

When a step belongs to another resource/page, the tour:

1. Calls `Livewire.navigate()` to the step URL (if available).
2. Waits for `livewire:navigated`.
3. Re-applies `data-tour` attributes and waits for the target element in the DOM.
4. Re-binds the modal overlay on the sidebar item.

This avoids stale DOM references after Filament replaces the page content.

### Welcome & finish steps

[](#welcome--finish-steps)

Steps without `attachTo` (default welcome/finish, or your custom `welcomeStep()` / `finishStep()`) are **centered** and use a **lighter experience**: the full-screen dark overlay is hidden so only the tooltip card is shown.

---

Localization (en / ar / id)
---------------------------

[](#localization-en--ar--id)

The package ships with simple translation files that you can override in your app:

- `resources/lang/en/filament-tour.php`
- `resources/lang/ar/filament-tour.php`
- `resources/lang/id/filament-tour.php`

Each file contains default labels for the welcome/finish steps and button texts. You can override them in your own application like any other Laravel lang file and then map them into your custom `welcomeStep()` / `finishStep()` calls, for example:

```
FilamentTourPlugin::make()
	->welcomeStep([
		'id' => trans('filament-tour.welcome.id'),
		'title' => trans('filament-tour.welcome.title'),
		'text' => trans('filament-tour.welcome.text'),
		'buttons' => [
			['text' => trans('filament-tour.welcome.buttons.skip'),  'action' => 'cancel',   'secondary' => true],
			['text' => trans('filament-tour.welcome.buttons.start'), 'action' => 'next',     'secondary' => false],
		],
	])
	->finishStep([
		'id' => trans('filament-tour.finish.id'),
		'title' => trans('filament-tour.finish.title'),
		'text' => trans('filament-tour.finish.text'),
		'buttons' => [
			['text' => trans('filament-tour.finish.buttons.back'),   'action' => 'back',     'secondary' => true],
			['text' => trans('filament-tour.finish.buttons.finish'), 'action' => 'complete', 'secondary' => false],
		],
	]);
```

---

Running the Tour
----------------

[](#running-the-tour)

- Click the tour icon in the Filament user menu (default `heroicon-o-academic-cap`).
- The tour starts at the welcome step (default or your custom `welcomeStep`).
- Dynamic steps run in order of `getTourStepSort()`.
- The final step is the finish screen (default or your custom `finishStep`).

### Progress persistence

[](#progress-persistence)

The tour stores state in the browser:

KeyPurpose`shepherd-tour-in-progress``"true"` while the tour is active`shepherd-tour-current-step`Current step `id` (e.g. `users`, `documents`)`shepherd-tour-completed`Set when the user finishes the tour`shepherd-tour-completed-at`ISO timestamp of completionIf the user refreshes or Livewire navigates during a tour, the script can resume from `shepherd-tour-current-step`.

### After complete or cancel

[](#after-complete-or-cancel)

`cleanupTourState()` runs automatically:

- Removes tour CSS classes (`.shepherd-tour-active-nav`, `.shepherd-target`, modal overlay).
- Clears in-progress `localStorage` keys.
- **Syncs sidebar active state** to the current URL (`fi-active` on the matching menu item only), so the dashboard is not incorrectly highlighted after visiting other pages during the tour.

---

Building Frontend Assets (package contributors)
-----------------------------------------------

[](#building-frontend-assets-package-contributors)

If you modify `resources/js/shepherd-tour.js`, rebuild the bundle:

```
cd packages/filament-tour   # or the package root in vendor
npm install
node bin/build.js
```

Output: `resources/dist/filament-tour.js`

Then publish to your app:

```
php artisan filament:assets
```

---

Troubleshooting
---------------

[](#troubleshooting)

### Highlight works on the first step only

[](#highlight-works-on-the-first-step-only)

1. Run `php artisan filament:assets` and hard‑refresh the browser.
2. Ensure `getTourStepId()` is unique across resources and pages.
3. Ensure the resource has an `index` URL (or the page is navigable).
4. Check the browser console for `Tour target not found for step "..."`.
5. Confirm sidebar labels match `getNavigationLabel()` or that the menu link `href` matches the step URL.

### Wrong sidebar item active after the tour

[](#wrong-sidebar-item-active-after-the-tour)

This is handled by `syncSidebarActiveState()` on complete/cancel. If you use a custom sidebar, ensure menu links use standard Filament classes (`.fi-sidebar-item`, `.fi-sidebar-item-btn`) and correct `href` paths.

### Custom welcome/finish still show a black screen

[](#custom-welcomefinish-still-show-a-black-screen)

Use `welcomeStep()` / `finishStep()` **without** `attachTo`. Centered steps hide the modal overlay automatically.

### Translations not applied to buttons in dynamic steps

[](#translations-not-applied-to-buttons-in-dynamic-steps)

Dynamic step buttons use `__('filament-tour::filament-tour.buttons.*')` from the collector. Publish or override lang files in your app under `lang/vendor/filament-tour/` if needed.

---

License
-------

[](#license)

Released under the MIT License.

###  Health Score

50

—

FairBetter than 95% of packages

Maintenance94

Actively maintained with recent releases

Popularity32

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~51 days

Total

4

Last Release

30d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1fb3960cf6e949bc5401902a09bf597da5bf4aeaf53c382bb55b1843769c0347?d=identicon)[Yacoub\_Al-haidari](/maintainers/Yacoub_Al-haidari)

---

Top Contributors

[![YacoubAl-hardari](https://avatars.githubusercontent.com/u/94101869?v=4)](https://github.com/YacoubAl-hardari "YacoubAl-hardari (8 commits)")

---

Tags

filament-plugintourlaraveltutorialguidefilamenttourfilament-touryacoubalhaidarishepherd

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/yacoubalhaidari-filament-tour/health.svg)

```
[![Health](https://phpackages.com/badges/yacoubalhaidari-filament-tour/health.svg)](https://phpackages.com/packages/yacoubalhaidari-filament-tour)
```

###  Alternatives

[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3914.6k](/packages/rawilk-profile-filament-plugin)[stephenjude/filament-jetstream

A Laravel starter kit built with Filament inspired by Jetstream.

17760.2k3](/packages/stephenjude-filament-jetstream)[awcodes/filament-quick-create

Plugin for Filament Admin that adds a dropdown menu to the header to quickly create new items.

251218.4k12](/packages/awcodes-filament-quick-create)[stephenjude/filament-two-factor-authentication

Filament Two Factor Authentication: Google 2FA + Passkey Authentication

84215.9k9](/packages/stephenjude-filament-two-factor-authentication)[marcelweidum/filament-passkeys

Use passkeys in your filamentphp app

6649.5k1](/packages/marcelweidum-filament-passkeys)[mradder/filament-logger

Audit logging, activity tracking, exports, alerts, and dashboards for Filament admin panels.

2317.4k](/packages/mradder-filament-logger)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)