Filament Inline Gauge Laravel Package

Getting Started

kainiklas/filament-gauge renders an inline SVG gauge — useful anywhere you'd otherwise show a bare percentage in a Filament panel (KPI columns, score tables, progress-style widgets).

Important — v0.2.0 is a breaking release: it renames the project. Before following any tutorial, blog post, or old README snippet, confirm you're on the v0.2.x package name. If you're upgrading from v0.1.x, treat this as a migration, not a bump:

composer remove kainiklas/<old-package-name>
composer require kainiklas/filament-gauge:^0.2

Then grep your app for anything referencing the old package name — composer.json, use statements, published config/views, Blade @includes, and any ->view('...') overrides. The new feature (CSS hooks) is additive and safe; the rename is not.

Minimal first use case — a gauge column in a resource table:

use Kainiklas\FilamentGauge\Tables\Columns\GaugeColumn; // verify namespace in the v0.2 README

GaugeColumn::make('completion_rate')
    ->label('Completion'),

Where to look first:

1. The package README on the v0.2.0 tag — not master, not your memory of v0.1.
2. vendor/kainiklas/filament-gauge/ — check composer.json (extra.laravel, psr-4), config/, and resources/views/ to see the real class namespaces and Blade structure after the rename.
3. Your Filament theme CSS — the second half of this release (style hooks) lives there, not in PHP.

Implementation Patterns

Table columns are the primary surface. Bind the gauge to a numeric attribute that's already on the model or a computed accessor. Keep the raw number visible too (->numeric() next to it, or a tooltip) — gauges are a glanceable summary, not a precise readout.

Normalize your scale in one place. If values are 0–100, 0–1, or arbitrary ranges, either pass the max/min explicitly on the column or wrap it in a model accessor. Doing the conversion inline in a dozen resources is how inconsistent gauges happen.

Forms and infolists. Gauges work well in read-only contexts — Placeholder, ViewField, or inside a custom widget. Avoid them in editable inputs; a gauge is an output, not an input, and swapping it into a form field confuses users about what's interactive.

Styling via the new CSS hooks (v0.2.0). This is the release's headline feature. Add rules to your Filament custom theme stylesheet rather than overriding the package's Blade views — view overrides break silently on the next patch.

/* resources/css/filament/admin/theme.css */
.fi-gauge { /* inspect the rendered markup for the exact hook names */ }

Rebuild after editing: npm run build. Because the hooks are new, inspect the actual DOM in the browser to get the real class/custom-property names — don't assume they match a convention.

Threshold-based coloring. Prefer a single reusable accessor or column factory (e.g. a GaugeColumn::make(...)->color(fn ($state) => ...)) over per-column closures, so a color-scheme change is one edit. Combine this with the CSS hooks: PHP decides which semantic state (good/warn/bad), CSS decides what that state looks like.

Dashboards and widgets. Gauges are compact enough to sit three-to-a-row in a stats overview widget. Pass pre-aggregated values from the widget query — don't let the column do per-row calculations across a large dataset.

Gotchas and Tips

• The rename is the whole gotcha. There was no v0.1.x → v0.2.0 shortcut. Uninstalling the old name and installing the new one is often required, because Composer treats them as different packages. composer remove both before you install to avoid two copies fighting over the same view namespace.
• Stale compiled views are the #1 "it's still broken" cause. After the rename: php artisan view:clear && php artisan optimize:clear, then php artisan filament:assets. Filament caches component views aggressively; old Blade paths will survive a naive cache:clear.
• Tailwind may purge your gauge styles. If your theme uses Filament's Tailwind setup, package classes only survive if the package's views are in the content globs of your tailwind.config.js (or @source directives in Tailwind v4). Symptom: the gauge renders but is unstyled in production while fine in dev.
• CSS hook specificity. Package styles and your override may be equally specific — if a rule "does nothing," check for a more specific selector or an inline style attribute on the SVG elements (SVG fill/stroke are commonly set inline and can't be beaten by a class without !important or a custom property).
• Watch the minor versions. At 0.x, a 0.3.0 can break you the same way 0.2.0 just did. Pin to ^0.2 with a committed composer.lock and read changelogs before running composer update.
• Debugging path when a gauge renders blank: (1) is the value null or a non-numeric string — cast it; (2) is the SVG sized to zero because the parent column has no width; (3) did the rename leave a stale view override in resources/views/vendor/ pointing at the old namespace. The last one is easy to miss and silently wins over the package view.
• Extension point to prefer: column configuration and CSS hooks. View overrides and subclassing are fine for a spike but will cost you on every release from a package still in 0.x.