Filament Simple Alert Laravel Package

Getting Started

Install against the right major. This package tracks Filament 4.x. Confirm your panel is on Filament 4 before you spend any time on it — the v4 line does not map backward to Filament 3. Pin exactly rather than floating, because the most recent patch (v4.0.5) is a correctness fix:

composer require codewithdennis/filament-simple-alert:4.0.5

Pin 4.0.5 explicitly if you want the undefined $getColor fix guaranteed, and widen the constraint only deliberately.

Read the source before the docs. With ~124 stars and zero downstream dependents, you are an early adopter, and the README is thinner than what you'd get from a large package. First stop is the repository's src/Components directory — it's a small surface area and confirms the exact class names and fluent methods available in your pinned version. Second stop is the README usage block. Third is the test suite, which is your best evidence of what's actually covered.

Register it if the version requires it. Check the README for whether your pinned version registers a plugin in the panel provider or is purely a component you use at the call site. Don't assume — this differs across the 3.x/4.x boundary. If plugin registration is required:

// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(SimpleAlertPlugin::make())
        // ...
}

First use case: a conditional environment banner. The cheapest thing to ship is an inline warning on a resource page that says something about the environment or a maintenance window. It exercises the component, the color/icon API, and conditional rendering all at once:

use CodeWithDennis\SimpleAlert\Components\Alert;

Alert::make('maintenance')
    ->title('Scheduled maintenance')
    ->description('Writes are disabled tonight between 22:00 and 23:00 UTC.')
    ->color('warning')
    ->icon('heroicon-o-wrench-screwdriver')
    ->dismissible()
    ->visible(fn () => now()->between(
        today()->setTime(20, 0),
        today()->setTime(23, 0),
    ));

Verify the FQCN against the README for your pinned version before copying — that's a one-minute check that saves a confusing Class not found.

Implementation Patterns

Wrap it before you use it. This is the single highest-value thing you can do in an afternoon. Put every alert through an application-level helper so no feature code imports the package namespace directly:

namespace App\Support;

use CodeWithDennis\SimpleAlert\Components\Alert;

final class AppAlerts
{
    public static function maintenance(): Alert
    {
        return Alert::make('maintenance')
            ->title('Scheduled maintenance')
            ->description(config('app.maintenance_notice'))
            ->color('warning')
            ->icon('heroicon-o-wrench-screwdriver')
            ->dismissible();
    }

    public static function saved(): Alert
    {
        return Alert::make('saved')
            ->title('Saved')
            ->description('Your changes have been applied.')
            ->color('success')
            ->icon('heroicon-o-check-circle');
    }
}

Now the package is referenced in exactly one file. API drift on upgrade has a one-file blast radius, and the removal cost if the maintainer goes quiet is roughly one day rather than a refactor.

Use it inside form and page schemas. The component behaves like any other schema element, so it slots in alongside fields:

public static function form(Schema $schema): Schema
{
    return $schema->components([
        AppAlerts::maintenance(),
        TextInput::make('name')->required(),
        // ...
    ]);
}

Ordering matters more than you'd expect: alerts placed at the top of a long form are seen, alerts buried between fields are skipped. Put severity callouts at the top, and put confirmations where the user's eye already is after acting.

Drive severity from one source of truth. Don't let every call site pick its own color and icon for the same semantic meaning. Centralize the mapping in the helper (AppAlerts::success(), ::warning(), ::danger(), ::info()) and let call sites supply only title and description. This is also what makes the $getColor regression path testable in one place.

Prefer Filament's native notifications for anything ephemeral. A post-save "saved!" flash after an action is usually better as a notification than as a rendered alert — notifications survive redirects, alerts in the schema do not. Reserve alerts for persistent, contextual messages: environment banners, deprecation notices, onboarding callouts, policy warnings above a form.

Test at the Livewire layer. You don't need to test the package — you need to test that your alert appears when it should:

Livewire::test(EditUser::class)
    ->assertSee('Scheduled maintenance');

// and the negative case, which is the one that actually breaks
Livewire::test(EditUser::class)
    ->travelTo(now()->addDay())
    ->assertDontSee('Scheduled maintenance');

Cover the visibility conditions and the custom-color path specifically. Those are the two places where a package change can silently alter behavior.

Gotchas and Tips

The $getColor fix is a maturity signal, not a guarantee. v4.0.5 fixed an undefined $getColor variable — which means the custom-color code path has a runtime defect history. Exercise severity colors and any custom color overrides explicitly after every bump. Don't assume the patch covered every branch; there's no evidenced regression test for it, so you own that test.

Silent invisibility is the real failure mode. If assets aren't published, the theme build conflicts, or a CSP blocks injected styles, the alert simply doesn't appear — no exception, no console error you'd attribute to a dependency. It presents as "the admin app is ignoring us." When an alert doesn't render, check in this order: plugin registered in this panel? assets published and rebuilt? browser console clean? CSP headers allowing the styles? Then check your visible() closure.

Dismissible is client-side only. Clicking the X almost certainly doesn't persist anything — the alert will return on the next page load or Livewire re-render. Do not build a "user acknowledged this banner" workflow on it. Per-user dismissal state is a database concern and belongs in your own model, not in a presentational package.

Don't stretch it toward notifications. Alerts here are static, code-authored, presentational. Per-user persistence, queued delivery, email, localization, and delivery guarantees are out of scope. The moment a requirement grows a "per user" or "remind them later" clause, escalate to Filament's native notification and database-notification APIs. Catching that early costs a conversation; late, it costs a rewrite.

Watch re-render behavior in Livewire forms. A schema component that's rebuilt on every Livewire update can lose its dismissed state mid-session, and a visible() closure that calls now() will flip mid-form if the user sits on the page across a boundary. For anything time-sensitive, compute the condition in the page's mount and store it, rather than evaluating per render.

Keep it off customer-facing surfaces. Brand fidelity, evidenced accessibility conformance, and support expectations all argue for owning the component yourself on anything a customer sees. This is admin chrome.

Write down the rollback before you roll out. Remove the plugin registration, composer remove codewithdennis/filament-simple-alert, fall back to a Blade partial. Because everything routes through AppAlerts, that's a contained change. Name one internal owner for upgrade validation and budget 1–2 days per Filament major upgrade to re-verify the alert surfaces, dark mode, and a production-shaped asset build.