Alert Box

• Features
• Requirements
• Installation
  • Automatic installation
  • Manual installation
• Usage
  • 🗂 Resource
  • 📄 Page
  • 🌐 Global
• Alert Configuration
• Available Render Hooks
  • Resource hooks
  • Page hooks
  • Global hooks
• Plugin Customization
  • Navigation
  • Page Access Control
    • Priority 1 — Filament Shield permission (highest)
    • Priority 2 — Custom ->authorize() closure
    • Priority 3 — Open access (default)
    • Summary
  • Colors
  • Builder UI
• Configuration
• Translations
• Views
• Filament Shield Integration
  • Automatic setup
  • Manual setup
  • Supported permissions
• Suggested Companion Plugin
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

A FilamentPHP plugin to define and display contextual alerts anywhere on your admin panel pages — Resources, custom Pages — using Filament's native render hooks system.

Alerts are managed through a dedicated settings page in your panel and stored in the database via spatie/laravel-settings. No code changes needed after initial setup.

#Features

• 3 alert scopes — Resource, Page, Global
• 6 built-in styles — info, tip, success, warning, danger, none
• Native Filament render hooks — place alerts at any registered hook point
• Settings UI — fully manage alerts directly from your Filament panel
• Live preview — see the alert render in real-time while editing
• Rich text content — editor with bold, italic, links, and more
• Multilingual — English and French included, fully translatable
• Highly customizable — colors, icons, navigation, authorization
• Custom hooks — extend with your own render hook names
• Shield Support — Built-in permission setup for Filament Shield

#Requirements

• PHP ^8.2
• FilamentPHP ^4.0 | ^5.0

AlertBox uses spatie/laravel-settings to store plugin settings. It's pulled in automatically as a Composer dependency — filament-alert-box:install publishes and runs its migration if you don't already have a settings table.

#Installation

Install the package via Composer:

composer require agencetwogether/filament-alert-box

[!IMPORTANT] If you have not set up a custom theme and are using Filament Panels follow the instructions in the Filament Docs (V4), Filament Docs (V5) first.

#Automatic installation

Run install command:

php artisan filament-alert-box:install

The installer will interactively guide you through:

• Publishing and running the database migrations (creates the settings table if needed)
• Seeding demo alerts
• Publishing the configuration file
• Publishing translations for customization
• Publishing views for customization
• Register the plugin in your Filament panel
• Register AlertBox styles in your custom Filament theme
• Configure Filament Shield permission

Then rebuild your assets:

npm run build

#Manual installation

Publish and run the migrations with:

php artisan vendor:publish --tag="filament-alert-box-migrations"
php artisan migrate

You can seed demo alerts using

php artisan db:seed --class=Agencetwogether\\AlertBox\\Database\\Seeders\\AlertBoxSeeder

You can publish the config file with:

php artisan vendor:publish --tag="filament-alert-box-config"

You can publish the translations using

php artisan vendor:publish --tag="filament-alert-box-translations"

You can publish the views using

php artisan vendor:publish --tag="filament-alert-box-views"

Register the plugin in your Filament panel provider:

use Agencetwogether\AlertBox\AlertBoxPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            AlertBoxPlugin::make(),
        ]);
}

Add the views to your theme.css

After setting up a custom theme add the following to your theme CSS file.

@source '../../../../vendor/agencetwogether/filament-alert-box/resources/views/**/*';

Then rebuild your assets:

npm run build

#Usage

Once installed, a "Manage alerts" page is added to your panel's navigation. From this page you can create and manage all your alerts without touching any code.

Each alert is defined as a block with one of three scopes:

#🗂 Resource

Displays an alert on one or more pages of a specific Resource.

• Select the Resource to target
• Optionally enable scope constraint to restrict to specific resource pages (Index, Create, Edit, View, etc.)
• Choose the hook where the alert should appear

#📄 Page

Displays an alert on a specific custom Page registered in your panel.

• Select the Page to target
• Choose the hook where the alert should appear

#🌐 Global

Displays an alert globally on all pages matching the selected hook.

• Choose the hook where the alert should appear
• Supports custom hooks defined in your configuration

#Alert Configuration

Each alert block, regardless of scope, shares a common set of fields:

#Available Render Hooks

The plugin exposes a curated list of Filament render hooks for each scope.

#Resource hooks

#Page hooks

#Global hooks

All Page hooks above, plus:

#Plugin Customization

All options are chainable on AlertBoxPlugin::make().

#Navigation

AlertBoxPlugin::make()
    ->navigationLabel('Alerts')
    ->navigationIcon('heroicon-o-bell-alert')
    ->navigationGroup('Settings')
    ->navigationSort(5)
    ->title('Alert Management'),

#Page Access Control

The ManageAlertBox settings page follows a three-level priority chain to decide whether the current user is allowed to access it. Each level is evaluated in order; the first one that applies wins.

#Priority 1 — Filament Shield permission (highest)

If Shield is installed in your project and you have generated the permissions for this page, access is controlled exclusively by the generated permission e.g. View:ManageAlertBox.

The page will be visible only to users (or roles) that have been granted that permission in your Shield configuration. The ->authorize() option described below is ignored in this case.

[!NOTE] If Shield is installed, but you have not yet run shield:generate, this level is skipped and the chain falls through to the next one. The page will not silently disappear while you are setting things up.

#Priority 2 — Custom ->authorize() closure

If Shield is not installed (or its permission has not been generated yet), you can restrict access with your own logic by passing a closure to the ->authorize() method when registering the plugin in your panel provider:

AlertBoxPlugin::make()
    ->authorize(fn (): bool => auth()->user()->isAdmin()),

The closure receives no arguments and must return a bool. It is evaluated on every request, so you can use any runtime check — roles, model attributes, feature flags, etc.:

AlertBoxPlugin::make()
    ->authorize(fn (): bool => auth()->user()->hasRole('editor')),

[!NOTE] This level is only reached when Shield is not managing access for this page. If Shield is active and the permission exists, this closure is never called.

#Priority 3 — Open access (default)

If neither of the above applies — Shield is not installed and ->authorize() was never called — the page is accessible to every authenticated user who has access to the panel. This is the default behavior and requires no configuration.

#Summary

#Colors

Override the default Tailwind colors for each alert style:

AlertBoxPlugin::make()
    ->colorInfo('blue')
    ->colorTip('violet')
    ->colorSuccess('emerald')
    ->colorWarning('amber')
    ->colorDanger('rose'),

#Builder UI

AlertBoxPlugin::make()
    ->blocksCollapsible()       // Allow collapsing alert blocks
    ->blocksCollapsed()         // Collapse all blocks by default (implies collapsible)
    ->iconResource('heroicon-o-table-cells')
    ->iconPage('heroicon-o-document')
    ->iconGlobal('heroicon-o-globe-alt')
    ->addActionAlignment(\Filament\Support\Enums\Alignment::Center),

#Configuration

After publishing the config file, you can customize:

// config/filament-alert-box.php

return [
    'page' => [
        'slug'    => 'alert-box',   // URL slug for the settings page
        'cluster' => null,          // Optional cluster class
    ],

    'toolbar_buttons' => [
        ['bold', 'italic', 'underline', 'strike', 'subscript', 'superscript', 'link'],
        ['undo', 'redo'],
    ],

    'default_icons' => [
        'info'    => Heroicon::OutlinedInformationCircle,
        'tip'     => Heroicon::OutlinedLightBulb,
        'success' => Heroicon::OutlinedCheckCircle,
        'warning' => Heroicon::OutlinedExclamationTriangle,
        'danger'  => Heroicon::OutlinedFire,
        'none'    => null,
    ],

    'default_colors' => [
        'info'    => 'sky',
        'tip'     => 'purple',
        'success' => 'green',
        'warning' => 'yellow',
        'danger'  => 'red',
        'none'    => null,
    ],

    // Add your own Filament render hooks here
    // See: https://filamentphp.com/docs/5.x/advanced/render-hooks
    'custom_hooks' => [
        // 'panels::my-custom-hook',
    ],
];

#Translations

The plugin ships with English and French translations. To customize them:

php artisan vendor:publish --tag=filament-alert-box-translations

Files will be published to lang/vendor/filament-alert-box/.

#Views

To customize the alert blade template:

php artisan vendor:publish --tag=filament-alert-box-views

Files will be published to resources/views/vendor/filament-alert-box/.

#Filament Shield Integration

The plugin ships with built-in support for Filament Shield. Shield is entirely optional — without it, "Manage alerts" page is accessible to any authenticated user unless you set explicitly authorize() method when you register the plugin.

#Automatic setup

If Shield is installed, the filament-alert-box:install command will generate permission entries via shield:generate

#Manual setup

If you prefer to set up Shield manually, or if the automatic setup didn't complete:

php artisan shield:generate --panel=admin --option=permissions

#Supported permissions

Manage alerts page has its own page-level permission managed by Shield.

#Suggested Companion Plugin

agencetwogether/hookshelper — A simple Filament plugin to toggle a visual overlay of all available render hooks on the current page. Very useful when configuring alert positions.

#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

• Max
• All Contributors

#License

This package is open-sourced software licensed under the MIT license.