Filament Advanced Widgets Laravel Package

Getting Started

Install and register. This is a Filament plugin-style package, so the setup is the familiar Laravel/Filament dance:

composer require eightynine/filament-advanced-widgets

Then register the plugin in your panel provider (app/Providers/Filament/AdminPanelProvider.php):

use EightyNine\AdvancedWidgets\AdvancedWidgetsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(AdvancedWidgetsPlugin::make())
        ->widgets([
            // your widgets
        ]);
}

As of 4.0.0 the package supports Filament v4 (it previously targeted v3). Confirm your installed Filament major version matches the package's composer.json constraint before you start — a v3 app pulling the 4.x tag (or vice versa) is the most common install failure. Check the vendor README first if the plugin class name or namespace differs from the above, then run php artisan filament:optimize (or php artisan optimize:clear) so the asset pipeline picks up any published CSS/JS.

Where to look first. Open vendor/eightynine/filament-advanced-widgets/src/ and locate the base widget classes. Advanced-widget packages almost always ship: a base class you extend, a set of chart/stat primitives, and a view layer under resources/views/. Read the base class before the README examples — you'll learn which lifecycle hooks (getData(), getOptions(), getCachedData()) you're expected to override, which differs from stock Filament widgets. If you're coming from 3.x, diff the Stat widget against the version you had installed: 4.0.0 adds RTL support here and fixes the labelColor / valueColor methods, so the stat API surface has shifted.

First use case. The fastest win is swapping one of your dashboard's StatsOverview or ChartWidget instances for the package's equivalent. Register it in getWidgets() on the page (or the panel), confirm it renders, then incrementally move data over:

public function getWidgets(): array
{
    return [
        \App\Filament\Widgets\AdvancedRevenueChart::class,
    ];
}

Once one advanced widget renders correctly, the rest of the package is mostly variations on the same pattern.

Implementation Patterns

Extend the provided base classes rather than composing around them. Advanced widget packages usually add behavior (polling, lazy hydration, persisted user preferences, actions) that lives in the base class. Subclassing gets you that for free; wrapping a stock Widget does not.

Keep data retrieval in the widget, keep formatting in the widget. A pattern that scales: override the data method to return an array or Collection, then configure presentation (chart type, thresholds, colors, labels) via fluent setters. This makes the widget testable with Livewire::test(RevenueChart::class)->assertSet('data', ...) and keeps the "what" separate from the "how it looks."

Set stat colors through the fluent methods, not overrides. If you subclass the stat widget, prefer ->labelColor(...) / ->valueColor(...) (the methods fixed in 4.0.0) over overriding render/view logic. If you're upgrading from 3.0.1 and had workarounds to force those colors, remove them — the fix landed in 4.x.

Let RTL handle itself. With 4.0.0's RTL support in the stat widget, don't hand-roll direction handling in your own view overrides. If your panel serves RTL locales, verify one stat widget renders correctly in an RTL locale before you publish and customize the view — a published stale view will bypass the new RTL logic entirely.

Pair with Filament's dashboard configuration. On Filament v3+ (and still true on v4), use per-user dashboards (->defaultDashboard(), CanCustomizeDashboard) and let this package's widgets fill them. The two systems compose cleanly: Filament owns who sees what, this package owns what each widget renders.

Poll only what needs polling. For "live" widgets, set the poll interval on the widget class rather than globally. protected static ?string $pollingInterval = '10s'; is the usual API; verify against the base class. Reserve polling for metrics that actually change (active users, queue depth) and leave historical charts static — you'll save a surprising amount of database load on busy dashboards.

Cache expensive aggregates at the widget boundary. Wrap your query in Cache::remember("widget.revenue.{$tenantId}", 300, ...), keyed by tenant/user where relevant. Advanced widget packages typically call their data method on every Livewire hydrate cycle, so an uncached COUNT(*) on a big table shows up immediately in page latency.

Use the package's action/render hooks for drill-downs. Most advanced-widget packages wire Filament Actions into chart elements. Wire "click a bar → open a filtered resource table" here instead of building custom JS. That gives you the full Filament modal/filter/notification stack for free.

Gotchas and Tips

Filament major version pinning is the #1 failure mode — and 4.0.0 is where it bites. This release exists specifically to add Filament v4 support, meaning the compatibility matrix has now split: 3.x for v3 apps, 4.x for v4 apps. If you're on Filament v4 you need 4.0.0+; if you're still on v3, do not blindly composer update into 4.x. Check the package's composer.json constraints and test matrix, and pin both Filament and this package in composer.json if you depend on a specific widget API.

Assets don't load until you publish or build. If a widget renders but looks unstyled or charts are blank, the usual cause is missing assets. Run the package's publish command if it has one (php artisan vendor:publish --tag=advanced-widgets-assets) and confirm the plugin is registered — Filament only registers package assets through the plugin, not the service provider alone. Re-publish after upgrading to 4.0.0; the asset set changed with v4 support.

Namespace changes between major releases. This package has moved things around across releases. If a class is "not found" after composer update, grep -r "class YourWidget" vendor/eightynine/filament-advanced-widgets/src/ and check the changelog. Don't assume the README's namespace matches the release you installed — especially across the 3.x → 4.x boundary.

Override views via publishing, not editing vendor. Publish the package views (vendor:publish --tag=advanced-widgets-views), then point the widget at your copy with protected static string $view = 'vendor.advanced-widgets.chart'; — the indirection means upgrades won't clobber your customization. Note that a view published before 4.0.0 will not contain the new RTL markup; re-publish or merge the RTL changes if you support RTL locales.

Debugging "widget shows nothing": check three things in order — (1) is the widget registered in getWidgets() or the panel? (2) does the data method return a non-empty result for the current user's tenant/permissions? (3) is the view actually resolved (inspect Livewire::test()->html())? Blank advanced widgets are almost always (2), caused by a global scope quietly narrowing results.

Extension points worth knowing: the base widget's getOptions() (or equivalent) for chart configuration, the getData() hook for data retrieval, and the canView() method for role-gating. If the package exposes a registerWidget() or configureUsing() API on the plugin, use it in a service provider to apply tenant-wide defaults instead of repeating settings in every subclass.

Test before you trust polling + actions together. Combine a polling widget with a modal-opening action and confirm the modal state survives a poll cycle — occasionally the refresh re-renders the widget and drops an open action modal. If that happens, drop the widget's polling interval or move the action to a non-polling variant.