Filament Custom Dashboard Widgets Laravel Package

Getting Started

This package ships Filament dashboard widgets that you register on a panel. The first release with a usable Packagist constraint is 1.0.2, so install with an explicit caret constraint rather than dev-main:

composer require johnrivera7/filament-custom-dashboard-widgets:^1.0

Where to look first, in order:

1. The service provider / plugin class in src/ — this tells you whether it registers as a Filament plugin (->plugin(CustomDashboardWidgetsPlugin::make()) in your PanelProvider) or as plain widgets you add manually to ->widgets([...]). The registration style determines everything else you do.
2. The widget classes — check which base widget they extend (Filament\Widgets\Widget, StatsOverviewWidget, ChartWidget, etc.), because that dictates the sort order, column span, and polling options available to you.
3. The published views — the 1.0.2 fix touches the Blade markup for images, so the views are where the layout behaviour actually lives. Publish them before you start customising so you have a diffable copy.
4. README — confirm whether a config file or assets need publishing; the release notes only mention the Composer install line, so treat anything not covered there as "inspect the source".

First use case: drop one widget onto an existing dashboard to confirm the panel picks it up, then iterate. Register it explicitly rather than relying on auto-discovery so you can see immediately whether a blank dashboard is a registration problem or a rendering problem:

public function panel(Panel $panel): Panel
{
    return $panel
        ->widgets([
            \JohnRivera7\FilamentCustomDashboardWidgets\Widgets\YourWidget::class,
        ]);
}

Once one widget renders, add the rest and start tuning column spans and sort order.

Implementation Patterns

Explicit registration over discovery. Filament's discoverWidgets() is convenient but makes it hard to reason about ordering and conditional visibility. For a package whose widgets are opinionated, register them by class on the panel and control order with ->sort() / the $sort property rather than relying on filesystem order.

Wrap widgets in your own subclasses. Rather than editing published views in place, extend the package widget and override getView() or the view data. You keep the package upgradeable and your customisations obvious in code review:

class TeamHeadcountWidget extends \JohnRivera7\...\Widgets\SomeWidget
{
    protected static string $view = 'widgets.team-headcount';
}

Keep image markup inside the widget's own view. The filament-hidden behaviour is applied to img tags directly. If you build a wrapper partial that renders the image, replicate the class placement there — do not assume the parent container's class will cascade into a hidden state.

Dashboard composition. Use Filament's getColumns() and getColumnSpan() overrides per panel rather than hardcoding grid classes in Blade. This keeps widgets reusable across an admin panel and a lighter "ops" panel without duplicating views.

Polling and performance. If any widget polls, set protected static ?string $pollingInterval explicitly and prefer a conservative interval. Dashboard widgets are the easiest place to accidentally run an expensive query every five seconds; if a widget is read-only, consider caching its data in the widget rather than polling the database.

Integration with the rest of the panel. Widgets that should appear on resource pages or custom pages are usually registered via getHeaderWidgets() / getFooterWidgets() on the page class, not the panel. Decide early whether these widgets belong on the dashboard only or are meant to be embeddable, because that changes how much you should couple them to dashboard assumptions.

Upgrade workflow. Because the package is at ^1.0 and just moved to stable minimum-stability, pin it in composer.json, commit the lockfile, and review the published views on each patch release. Patch releases here can change markup (1.0.2 is exactly that), so a visual regression check on the dashboard after upgrading is worth the two minutes.

Gotchas and Tips

The 1.0.2 image fix is a markup change — check your overrides. filament-hidden is now applied directly on the img tag. If you published the views on 1.0.0 or 1.0.1 and edited them, re-publish or diff against the new version. A stale override will keep the old wrapper-class behaviour and the hide toggle will silently stop working, with no error to point at it. This is the most likely thing to bite you on upgrade.

minimum-stability: stable is about consumers, not you. If your root composer.json sets minimum-stability: dev, it does not change how this package resolves — but it does mean other packages you add may pull unstable versions. If you were previously requiring this package via a dev- branch alias, switch to the ^1.0 constraint now and run composer update johnrivera7/filament-custom-dashboard-widgets --with-dependencies to confirm it resolves without the alias.

Blank widget on the dashboard. Almost always one of: the widget class is not registered on the panel, the panel is cached, or the widget's canView() returns false. Run php artisan filament:clear-cached-components (and view:clear) before debugging the Blade file — Filament caches component discovery aggressively and a cached panel will ignore your new registration.

Cached views mask view changes. After publishing or editing a widget view, php artisan view:clear is mandatory in any environment with view caching enabled. A "my change did nothing" report is usually a compiled view.

Hidden images still load. Applying filament-hidden to the img tag hides it visually; the browser may still fetch the source. If the widget displays remote avatars or generated thumbnails, consider not rendering the src at all for hidden states rather than relying on the CSS class — otherwise you pay the network cost for content nobody sees.

Column span is per-widget, not per-panel. If a widget looks cramped, check getColumnSpan() on the widget before touching the panel's column count. Changing the panel's ->columns() affects every widget on the dashboard, including ones you did not write.

Extension points to prefer. Overriding the view and the widget's data method is stable across patch releases. Overriding protected properties by string name, or reaching into the package's internal view data keys, is not — 1.0.2 demonstrates that template-level details can change in a patch. If you need behaviour the package does not expose, a subclass plus a custom view is the durable path; a copied-and-pasted view is the fragile one.

Report issues with the exact version. With three releases in the 1.0 line and a markup fix in the latest, an issue report without the installed version is hard to action. composer show johnrivera7/filament-custom-dashboard-widgets output plus your Filament major version is the minimum useful context.