atendwa / filament-page-guide
A "Guide" button and modal for Filament pages, showing a Blade view that explains the page.
Requires
- php: ^8.3
- filament/filament: ^5.0
- illuminate/support: ^12.0|^13.0
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.27
- orchestra/testbench: ^10.0|^11.0
- pestphp/pest: ^4.0
- pestphp/pest-plugin-arch: ^4.0
- pestphp/pest-plugin-laravel: ^4.0
- rector/rector: ^2.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 02:39:47 UTC
README
Adds a Guide button to Filament pages. It opens a full-width modal that shows a Blade view explaining the page: what it is for, what each part means and how to use it. Guides are plain Blade views, so they live with your application and can use any HTML. Nothing is shown when a page has no guide, or when its view does not exist.
Requirements
PHP 8.3 or later, Laravel 12 or 13 and Filament 5.
Installation
composer require atendwa/filament-page-guide
Register the plugin on each panel that shows guides (it adds the modal's styles):
use Atendwa\PageGuide\Filament\PageGuidePlugin; $panel->plugins([ PageGuidePlugin::make(), ]);
Then run php artisan filament:assets so the stylesheet is published.
Configuration
Both are off by default. Set them on the plugin:
PageGuidePlugin::make() ->footer(['Kind regards,', 'The support team', 'support@example.com']) ->decoration('components.guide-artwork');
footer()takes lines shown at the bottom of every guide (empty lines are skipped). The first line is emphasised.decoration()takes the name of a Blade component rendered beside the guide on large screens (for example an illustration). It receives aclassattribute to fill the space.
The plugin stores both in the page-guide.footer and page-guide.decoration config keys, so they can also be set with
config([...]) in a service provider.
Usage
Use the trait on any Filament page (list, view, custom pages) and name the guide view:
use Atendwa\PageGuide\Concerns\HasPageGuide; class ListOrders extends ListRecords { use HasPageGuide; public function getPageGuide(): ?string { return 'guides.orders'; } }
The trait adds the button through the page's actions(). If your page builds its own header actions, include
$this->pageGuideAction() where you want the button.
Write the guide with the component the package provides:
{{-- resources/views/guides/orders.blade.php --}} <x-pageguide::partials.guide title="Working with orders"> <p>Orders appear here as soon as they are paid.</p> <ul> <li><strong>Status:</strong> where the order is in fulfilment.</li> </ul> </x-pageguide::partials.guide>
Extending
| Method | Effect |
|---|---|
getPageGuideHeading() |
modal heading; defaults to the page heading followed by "Guide" |
getPageGuideIcon() |
modal icon; defaults to heroicon-o-book-open |
Testing
composer install
composer quality # Pint, Rector, PHPStan (max), Pest
Changelog
See CHANGELOG.md.
License
MIT. See LICENSE.md.