Plugins
Support
Visit GitHub
Tour
Bring the power of DriverJs to your Filament panels and start a tour to let your users discover your dashboard !
Form Builder
Table Column
Table Builder
Form Field
Dark theme support
Yes
Multi language support
Yes
Compatible with the latest version
Supported versions: 2.x - 3.x
Documentation

With the power of DriverJS bring to your users an elegant way to discover your panels !

#Installation

You can install this filament plugin via composer:

For Filament V3.x

composer require jibaymcs/filament-tour:"^3.0"

For Filament V2.x

composer require jibaymcs/filament-tour:"^2.0"

You can publish the config file with:

php artisan vendor:publish --tag="filament-tour-config"

Optionally, you can publish the views using

php artisan vendor:publish --tag="filament-tour-views"

This is the contents of the published config file:

 return [
    "only_visible_once" => true,
];

#Usage

public function panel(Panel $panel) {
    return $panel->default()
        ->[...]
        ->plugins([ FilamentTourPlugin::make() ]);
}

You can also enable or disable the check on the local storage if the current user have already seen the tour.

// default  : true
FilamentTourPlugin::make()->onlyVisibleOnce(false)

Let's follow this example to add a tour to your dashboard page.

If you don't already have a customized dashboard, please refer to the following tutorial: FIlamentPHP - Dashboard - Customizing the dashboard page

#Use the correct trait to registers your tours !

<?php
namespace App\Filament\Pages;
 
use JibayMcs\FilamentTour\Tour\Tour;
 
class Dashboard extends FilamentDashboard {
 
    use HasTour;
    // ...
 
    public function tours(): array    {
        return [];
        }
}

#Create a simple tour !

public function tours(): array {
    return [
       Tour::make('dashboard')
           ->steps(
 
               Step::make()
                   ->title("Welcome to your Dashboard !")
                   ->description(view('tutorial.dashboard.introduction')),
 
               Step::make('.fi-avatar')
                   ->title('Woaw ! Here is your avatar !')
                   ->description('You look nice !')
                   ->icon('heroicon-o-user-circle')
                   ->iconColor('primary')
           ),
    ];
}

#Create a JSON tour !

#- From a direct URL

public function tours(): array {
    return [
       Tour::make(url: "https://gist.githubusercontent.com/JibayMcs/cc06efddadcfc0a0ff59e116533ee727/raw/8c5c86a3a4b92e4d0586d7a344d0e41f0c175659/TourDashboard.json")
    ];
}

#- From your Storage

public function tours(): array {
    return [
       Tour::make(json: Storage::disk('local')->get("TourDashboard.json"))
    ];
}

❗ Important: Using Tour::make(url: "") or Tour::make(json: "") is the same thing, so don't worry about the name of your parameter if you've got the wrong type.
BUT
If you use Tour::make('my-tour') it's equal to Tour::make(id: 'my-tour') And here you need to construct all your steps. No JSON reading here.

JSON Example file (click to expand) or Github Gist Link 
{
    "id": "dashboard",
    "route": "/admin/test-team",
    "colors": [
        "",
        ""
    ],
    "alwaysShow": true,
    "visible": true,
    "uncloseable": true,
    "ignoreRoutes": false,
    "disableEvents": true,
    "nextButtonLabel": "Next",
    "previousButtonLabel": "Previous",
    "doneButtonLabel": "Done",
    "steps": [
        {
            "title": "Woaw ! First Step !",
            "description": "Yeah ! And I'm from a json file !",
            "uncloseable": false,
            "events": {
                "clickOnNext": "body",
                "notifyOnNext": {
                    "title": "Hello World !",
                    "body": "Woaw ! I'm from a Json file !",
                    "color": "success"
                },
                "redirectOnNext": {
                    "url": "https://filamentphp.com",
                    "newTab": true
                },
                "dispatchOnNext": [
                    "open-modal",
                    {
                        "id": "edit-user"
                    }
                ]
            }
        },
        {
            "title": "An other one !",
            "description": "Yeah ! And I'm from the same json file !",
            "uncloseable": false,
            "events": {
                "clickOnNext": "body",
                "notifyOnNext": {
                    "title": "Hello World !",
                    "body": "Woaw ! I'm from a Json file !",
                    "color": "success"
                },
                "redirectOnNext": {
                    "url": "https://filamentphp.com",
                    "newTab": true
                },
                "dispatchOnNext": [
                    "open-modal",
                    {
                        "id": "edit-user"
                    }
                ]
            }
        }
    ]
}

#Tour methods reference

// Instanciate a tour, and provide an id, to trigger it later
Tour::make(string $id)
 
// Since 3.1.0.1, JSON Support update
Tour::make(... $params)
 
    // Define a custom url to trigger your tour
    ->route(string $route)
 
    //Register the steps of your tour
    ->steps(Step ...$steps)
 
    // Define a color of your hightlight overlay for the dark and light theme of your filament panel
    ->colors(string $light, string $dark)
 
    //Set the tour as always visible, even is already viewed by the user.
    ->alwaysShow(bool|Closure $alwaysShow = true)
 
    // Set the tour visible or not
    ->visible(bool|Closure $visible = true)
 
    // Set the 'Next' button label
    ->nextButtonLabel(string $label)
 
    // Set the 'Previous' button label
    ->previousButtonLabel(string $label)
 
    // Set the 'Done' button label
    ->doneButtonLabel(string $label)
 
    // Set the whole steps of the tour as uncloseable
    ->uncloseable(bool|Closure $uncloseable = true)
 
    // Disable all tour steps events
    ->disableEvents(bool|Closure $disableEvents = true)
 
    // Bypass route check to show the tour on all pages
    // Maybe useless, but who knows ?
    ->ignoreRoutes(bool|Closure $ignoreRoutes = true)

#Step methods reference

// If no element provided, the step act like a modal
Step::make(string $element = null)
 
    // Define the title of your step
    // Mandatory
    ->title(string|Closure $title)
 
    // Define the description of your step
    // Also accept HTML
    // Mandatory
    ->description(string|Closure|HtmlString|View $description)
 
    // Define an icon next to your step title
    ->icon(string $icon)
 
    // Define the color of the title icon
    ->iconColor(string $color)
 
    // Step your step closeable or not
    // Default: true
    ->uncloseable(bool|Closure $uncloseable = true)
 
    //Simulate a click on a CSS selected element when you press the next button
    ->clickOnNext(string|Closure $selector)
 
    // Send a notification when you press the next button
    ->notifyOnNext(Notification $notification)
 
    //Redirect you to a custom url or a route() when you press the next button
    ->redirectOnNext(string $url, bool $newTab = false)
 
    // Dispatch an event like `$dispatch()` when you press the next button
    ->dispatchOnNext(string $name, ...$args)

Same as tour, use the correct trait !

  • Use the correct trait to registers your highlights !
<?php
 
namespace App\Filament\Pages;
 
use JibayMcs\FilamentTour\Highlight\HasHighlight;
 
class Dashboard extends FilamentDashboard {
 
    use HasHighlight;
    // ...
 
    public function highlights(): array {
        return [];
    }
}
  • Create a simple highlight element !
public function highlights(): array {
 
    return [
 
        Highlight::make('.fi-header-heading')
            ->element('.fi-header-heading')
            ->title('Whoaw ! You highlighted the title of the page !')
            ->description('"Dashboard"'),
 
        Highlight::make('.fi-avatar')
            ->element('.fi-avatar')
            ->title("Pssst ! That's your avatar")
            ->icon('heroicon-o-user-circle')
            ->iconColor('primary'),
 
    ];
}

#Highlight methods reference

// Instanciate a highlight with a CSS select of the element where the icon button is next to
Highlight::make(string $parent)
 
    // Define the element to be highlighted
    ->element(string $element)
 
    // Set the title of your highlight
    ->title(string|Closure $title)
 
    // Set the description of your highlight
    ->description(string|Closure|HtmlString|View $description)
 
    // Define a custom icon for your highlight button
    // Default: heroicon-m-question-mark-circle
    ->icon(string $icon)
 
    // Define the color of the highlight icon button
    // Default: gray
    ->iconColor(string $color)
 
    // Define a color of your hightlight overlay for the dark and light theme of your filament panel
    ->colors(string $light, string $dark)
 
    // Set the position of your icon button around the parent
    // Default: top-left
    // Available: top-left, top-right, bottom-left, bottom-right
    ->position(string $position)

#Avalaible events:

  • filament-tour::open-highlight string id
    Open a specific highlight by its id.

  • filament-tour::open-tour string id
    Open a specific tour by its id.

Filament Tour, dispatch some event to show tours and highlights. So you can trigger them from your own code.

Basically, if you want a custom button to trigger a tour or a highlight, you can do something like this:

// ======== Highlights
// AlpineJS
<button x-on:click="Livewire.dispatch('filament-tour::open-highlight', 'title')">Show title highlight</button>
 
// Livewire
<button wire:click="$dispatch('filament-tour::open-highlight', 'title')">Show title highlight</button>
 
// ======== Tours
//AlpineJS
<button x-on:click="Livewire.dispatch('filament-tour::open-tour', 'title')">Show Dashboard tour</button>
 
// Livewire
<button wire:click="$dispatch('filament-tour::open-tour', 'dashboard')">Show Dashboard tour</button>

ℹ️
Don't forget to prefix your event with filament-tour:: to trigger the correct event.

❗ Important: This tool is always disabled in production mode. APP_ENV=production

Filament Tour embed a simple tool to help you to develop your tours and highlights.

Let me show you how to use it !

#Enable the tool

To enable the tool, simply use FilamentTourPlugin::make()->enableCssSelector() in your plugin declaration.

#Keyboard shortcuts

Ctrl|Cmd + Space To open the tool.

Escape To exit the tool.

Ctrl|Cmd + C To copy the CSS Selector of the highlighted element.

CSS Selector Tool Utilisation Preview

#DriverJS

The core of this plugin !
Don't hesitate to check the documentation to learn more about the possibilities of this plugin.
I don't implemented all the features of DriverJS, at this time, but I'm working on it !

#Changelog

Please see CHANGELOG for more information on what has changed recently.

#Contributing

Please see CONTRIBUTING for details.

#Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

#Credits

#License

The MIT License (MIT). Please see License File for more information.

Jibay Mcs

Jibay Mcs is a self-taught full-stack developer currently working for a French company. A former lumberjack, he has always had a passion for development.

1
Plugins
54
Stars
Featured Plugins