Requirements

Nova 6 is explicitly conflicted rather than merely untested, so Composer will refuse the combination instead of letting you find out at runtime. laravel/nova is a runtime requirement in 2.0, not a dev dependency.

The Nova floor is 5.11, not 5.7, for one reason: Field::configureDefaults() arrives in 5.11, and that is the hook this field applies exceptOnForms() and the inline default through. The override is declared with PHP’s #[Override] attribute, so on an older Nova the class fails to load at all — which is the failure you want. Without the attribute the class would load, the hook would never run, and the field would quietly appear on create and update forms.

Install

composer require gabrielesbaiz/nova-field-indicator

There is nothing to register. The service provider is auto-discovered and adds its script and stylesheet inside Nova::serving().

Publishing config and translations

Both are optional — the defaults are usable as they are.

php artisan vendor:publish --tag=nova-field-indicator-config
php artisan vendor:publish --tag=nova-field-indicator-lang

English and Italian ship with the package. Labels pass through __() by default, and Laravel returns an unknown key unchanged, so this is a no-op until you translate something.

Your first field

use Gabrielesbaiz\NovaFieldIndicator\NovaFieldIndicator;

public function fields(NovaRequest $request): array
{
    return [
        NovaFieldIndicator::make('Status')->colors([
            'active'  => 'success',
            'banned'  => 'danger',
            'invited' => 'info',
        ]),
    ];
}

Labels are optional: an unmapped value falls back to itself, exactly as Nova’s own Badge behaves.

Labels, colours and icons

Each value gets a state. Configure the parts separately, or all at once with states() — they write to the same table.

NovaFieldIndicator::make('Status')
    ->labels(['active' => 'Active', 'banned' => 'Banned'])
    ->colors(['active' => 'success', 'banned' => 'danger'])
    ->icons(['active' => 'check-circle', 'banned' => 'x-circle']),

NovaFieldIndicator::make('Status')->states([
    'active' => [
        'label'   => 'Active',
        'color'   => 'success',
        'icon'    => 'check-circle',
        'tooltip' => 'Account is active',
    ],
    'syncing' => ['label' => 'Syncing', 'color' => 'sky-400', 'pulse' => true],
]),

Calling icons() turns icons on by itself. Icons are heroicons rendered by Nova’s own component, so they add nothing to this package’s bundle.

Enum-first

The shortest path. Implement one, two or all three contracts on an enum you already have; anything you leave out falls back sensibly.

use Gabrielesbaiz\NovaFieldIndicator\Contracts\{HasColor, HasIcon, HasLabel};
use Gabrielesbaiz\NovaFieldIndicator\Enums\Color;

enum Status: string implements HasColor, HasIcon, HasLabel
{
    case Active = 'active';
    case Banned = 'banned';

    public function indicatorLabel(): ?string
    {
        return match ($this) {
            self::Active => 'Active',
            self::Banned => 'Banned',
        };
    }

    public function indicatorColor(): Color|string|array|null
    {
        return match ($this) {
            self::Active => Color::Success,
            self::Banned => 'danger',
        };
    }

    public function indicatorIcon(): ?string
    {
        return match ($this) {
            self::Active => 'check-circle',
            self::Banned => 'x-circle',
        };
    }
}

The methods are named indicator* rather than getLabel() so an enum can implement Filament’s contracts and these side by side without a clash.

An enum implementing none of the contracts still works: case names are humanised, so InReview becomes “In review”.

Shapes and sizes

->dot()  ->ring()  ->square()  ->pill()
->shape(Shape::Ring)        // or the enum
->size('sm')                // sm | md | lg
->withoutLabel()            // the mark only, no text
->pulse()

Measurements live in the stylesheet, so the payload carries a token rather than pixels and a new size never changes the wire format.

Continuous values

A state table cannot enumerate a percentage. ranges() takes inclusive lower bounds and sorts them itself, so declaration order does not matter.

NovaFieldIndicator::make('Health')->ranges([
    0  => 'danger',
    50 => 'warning',
    80 => 'success',
]),

// or with labels per band
->ranges([
    0  => ['label' => 'Critical', 'color' => 'danger'],
    50 => ['label' => 'Healthy',  'color' => 'success'],
])

A non-numeric value skips the table entirely and falls back to the default colour.

Hiding values

->hideWhen('active')                    // one value
->hideWhen(['invited', 'requested'])     // several
->hideWhen(fn ($value) => $value === 'inactive')
->hideWhenEmpty()                       // null, false, 0, '' and '0'

A hidden field short-circuits: nothing is resolved for it at all, so the cost is not paid per row.

Filtering

Call filterable() and the field builds its own select-filter options from the state table, or from the enum when there is one.

NovaFieldIndicator::make('Status')->enum(Status::class)->filterable(),

If there is nothing to offer — a field configured only with colorUsing(), say — no filter is registered, rather than an empty dropdown.

Accessibility

WCAG 1.4.1 says colour must not be the only visual means of conveying information. About one man in twelve has some form of colour vision deficiency, and a greyscale print has none at all. This package gives you three channels and uses the first by default:

1. A visible label — on by default. The text is the meaning; the mark reinforces it.
2. A distinct icon per state, via withIcons().
3. A distinct shape per state — a ring for pending, a square for queued.

For screen readers the field switches behaviour based on whether text is visible, because the two cases need opposite treatment:

Icons are always aria-hidden; they are a redundant channel for sighted users, never the name. The pulse animation is wrapped in prefers-reduced-motion, and forced-colors mode keeps the mark visible with a CanvasText border.

Nova’s palette, not ours

Nova emits every Tailwind colour at :root as --colors-<family>-<shade>, holding the channels only — 34, 197, 94 rather than a finished colour. A token resolves to a family and two shades, and is used as rgba(var(--colors-green-500)).

That indirection is the whole point: an application that re-themes Nova re-themes every indicator, with no CSS of its own. Version 2 hard-coded fifteen Tailwind v1 hex values, which could not follow a theme and could not express a dark variant.

The built-in tokens

Nine names, resolved for you. The first four are the ones that rendered invisibly in 1.x.

Every accepted form

Resolution is ordered. The first rule that matches wins.

Literals are allow-listed

A resolved colour becomes an inline custom property, so a literal that could close a declaration would be a CSS injection. Validation happens once, server-side, against an anchored pattern.

Capped at 64 characters. The Vue component does no pattern matching at all — it binds a style object, which the browser parses and discards if unparseable.

Rebranding a token

Application tokens are resolved before the built-ins, so you can redefine success itself once rather than at forty call sites.

'colors' => [
    'tokens' => [
        'brand'   => ['light' => 'violet-600', 'dark' => 'violet-400'],
        'success' => 'emerald-600',   // override a built-in
        'green'   => '#38C172',      // pin a 1.x colour exactly
    ],
],

The palette wall

Every family Nova emits, at every shade, with the name to pass to colors(). Click any swatch to copy the call.

The swatches here are approximations of the Tailwind ramp, drawn by this page. The exact values come from whatever your Nova build defines for --colors-* — which is the entire point of resolving against them. The names are exact.

Click a swatch to copy its PHP.

Publishing

php artisan vendor:publish --tag=nova-field-indicator-config

The keys

What is deliberately not configurable

• The family and shade table. It is Nova’s, not ours — mirroring it in config would let the two drift.
• The CSS literal allow-list. It is a security boundary. See Security.
• Component and asset handles. Renaming them would break published overrides for no benefit.

Translations

The package ships en and it. Keys are Unknown, Not set, Yes and No — the labels boolean() and unknown() produce in PHP.

The service provider registers them with both Nova’s JavaScript translator and Laravel’s PHP translator, because this package resolves labels server-side. Registering only the first — which is the more common pattern — would leave those keys untranslated.

Content

Closure resolvers

Each receives (mixed $value, mixed $resource) and wins over the state table.

Appearance

Visibility and filtering

Nova’s own field methods all apply as usual — sortable(), onlyOnDetail(), readonly() and the rest. The field is Unfillable and calls exceptOnForms(), so it never appears on a form.

Enums and contracts

Plain palette families are deliberately not enum cases. They resolve as families instead, which is what lets the configured default shades apply to them.

Extending

NovaFieldIndicator is not final: subclassing is the documented extension point. Override resolveIndicatorFor(string|int|null $key, mixed $resource) — it is the single seam the rest of the field depends on.

Resolution itself is framework-free. Nothing under Support, Results, Enums or Contracts references Nova, which is enforced by an architecture test and is why the colour and enum logic can be unit-tested without booting an application.

Reporting

Please report security issues to gabriele@sbaiz.com rather than opening a public issue.

Threat model

This field renders a colour-coded mark. It never renders HTML, never uses v-html, and never echoes an attribute value as markup — so the usual stored-XSS surface of a Nova field does not apply.

The one boundary that does exist is CSS, because a configured colour becomes an inline custom property.

• Colour values are validated server-side against an anchored allow-list before they are serialized.
• Anything containing ; { } /* \ < > url( expression( image-set( or javascript: is rejected with an exception.
• The Vue component does no pattern matching on colours. It binds a style object, which Vue applies through setProperty(), so an unparseable value is dropped by the browser rather than concatenated into a declaration.

Nova credentials

auth.json holds your Nova licence credentials. It is listed in .gitignore and marked export-ignore in .gitattributes, so it is neither committed nor shipped in a distributed tarball. If you fork the package, verify both before pushing.

Start here

composer require gabrielesbaiz/nova-field-indicator:^2.0
php artisan nova-field-indicator:upgrade --dry-run

Review the output, then run it without the flag. It is idempotent, so running it twice is safe — but commit first, because it rewrites files in place.

It rewrites what is mechanical and reports what needs a human. Read that report: the first entry in it is the one that can bite silently.

1. Four colours were invisible and now appear

This is the reason 2.0 exists, and it is a fix that reads as a change.

In 1.x, success, danger, warning and info were styled as var(--success) and friends. Those CSS variables existed in Nova 3 and 4. Nova 5 does not define them, so the mark painted with an invalid colour and rendered completely transparent.

2. Every named colour shifts hue

1.x hard-coded the Tailwind v1 palette. 2.0 resolves to Nova’s, which is Tailwind 3.

The upgrade command rewrites any of these hexes it finds in a colors() call. To keep an exact old value, pass a literal, or pin the token once in the published config.

3. Custom .indicator-* CSS stops applying

1.x invited this, because colours were class names — .indicator-brand { background: #123456 } in your stylesheet, then ->colors(['active' => 'brand']).

2.0 emits no indicator-* class at all, so those rules are dead and the value falls back to neutral grey. This is the sharpest real break in the release, and it is deliberate: keeping a legacy hook class would re-create exactly the stylesheet-source-order fragility being removed.

->colors(['active' => '#123456']),

4. Renamed and removed methods

There are no deprecation shims. A missed call site raises BadMethodCallException, which is a better failure than a silently wrong one.

5. withoutLabels() is gone — read this one carefully

The names are one character apart and the meanings are nearly opposite, so it is worth being explicit.

1.x withoutLabels() meant “print the raw value instead of a mapped label”. In 2.0 that is simply the default: an unmapped value falls back to itself. In almost every case you just delete the call, and the command does that for you when the file contains no labels() at all.

2.0 withoutLabel(), singular, is a different feature: render the mark with no text at all. Reach for it only if that is genuinely what you want.

If the file also uses labels() anywhere, the command leaves withoutLabels() alone and flags it rather than guessing which chain it belongs to. Where it sat on a chain with labels(), that combination was contradictory in 1.x — the labels were ignored — so decide which one you meant.

6. A string is no longer a possible callback

// 1.x: is_callable('trim') was true, so trim() was INVOKED as the predicate.
// 2.0: 'trim' is a value, compared against the attribute.
->hideWhen('trim')

// If you wanted the callback:
->hideWhen(fn ($value) => trim($value) === '')

The command reports every shouldHide() whose argument names a real PHP function. Scalar comparison is otherwise unchanged: both sides are normalised first, so 0 still matches '0' the way it did under 1.x’s ==.

7. The field is read-only on forms

It implements Unfillable and calls exceptOnForms(), so it is hidden on create, update, attach and update-attached — the last two of which the old $showOnCreation/$showOnUpdate pair missed. The 1.x form component was registered and bundled but unreachable and never wrote a value, so nothing can regress.

Select::make('Status')->options($options)->onlyOnForms(),
NovaFieldIndicator::make('Status')->enum(Status::class),

8. The payload changed

Only relevant if you read the serialized field from the API or wrote your own Vue override. labels, colors, unknownLabel, withoutLabels are gone, replaced by an indicators list. The component is renamed from indicator-field to nova-field-indicator, and the asset handles from indicator to the same.

Subclasses that override resolveForDisplay() should override resolveIndicatorFor() instead; resolution moved to jsonSerialize().

2.0.1 — performance

Serializing a row is about 28% faster: 0.086 ms → 0.062 ms per row for a four-state states() table, and 0.075 ms → 0.054 ms for ->enum() (minimum of five runs, PHP 8.4, 2000 rows each). The API and the payload are unchanged.

• One configuration read per field instead of eleven. Nova rebuilds the field for every row, so a 50-row index with three indicator columns was making over 1,600 container lookups for values that cannot change between rows.
• The token map is lowered once, in the resolver’s constructor, rather than rebuilt inside both the membership test and the read on every colour.
• Family and shade membership are hash lookups, not scans over 23 families and 11 shades.
• ->ranges() is matched once per value, not twice.
• Numeric state keys use ctype_digit() rather than a regex, and colours are memoized per value within a field.

2.0.0 — requirements

• Requires PHP 8.3+, Laravel 12 or 13, and Nova 5.11+ (Nova 6 is explicitly conflicted).
• Dropped PHP 8.0–8.2 and Laravel 10 and 11.
• laravel/nova is now a runtime requirement rather than a dev dependency.

Fixed

• success, danger, warning and info rendered an invisible dot on Nova 5. They were styled as var(--success) and friends — variables Nova 3 and 4 defined and Nova 5 does not. If you used these tokens, dots will now appear where your index looked empty.
• shouldHide('trim') silently invoked trim() instead of comparing against the string, because is_callable() was tested before the value branch.
• Colour literals are now validated server-side against an anchored allow-list before they reach an inline style.
• whitespace-no-wrap was Tailwind v1 syntax and had done nothing since Nova 4.
• The neutral colour no longer depends on stylesheet source order.
• Dark mode is supported at all, for the first time.
• The generic indicator asset handle, which any other package could collide with.

Added

• ->enum(Status::class) derives labels, colours and icons from one enum. A value that is a backed enum self-describes with no configuration at all.
• ->states(), shapes, three sizes, icons, ->ranges(), ->boolean(), the four closure resolvers, and ->pulse().
• ->filterable(): the field implements FilterableField and builds its own select-filter options.
• Accessibility: the mark is decorative when a label is visible and becomes a named role="img" when colour alone carries the meaning. Forced-colors mode is handled.
• Arbitrary Tailwind palette colours, light/dark pairs, and literal CSS colours as first-class values.
• A publishable config file, including a colors.tokens table for rebranding a token once.
• English and Italian translations.
• php artisan nova-field-indicator:upgrade.
• Real test coverage: 164 Pest tests and 22 Vitest tests, PHPStan level 6.

Changed

• Labels and colours are resolved on the server. 1.x pushed the whole configuration into every row of an index; the payload now carries one resolved indicator per value.
• Colours resolve to Nova’s own --colors-* variables. The built-in names now match the Tailwind 3 palette.
• The field is Unfillable and hidden on every form view.
• Vite 6 replaces Laravel Mix. Output paths are unchanged.
• The Vue component is now nova-field-indicator.
• The bundle is 1.07 kB gzipped, down from 1.4 kB, despite the added features.

Removed

• shouldHide(), shouldHideIfNo() and withoutLabels() — see Upgrading.
• The .indicator-* CSS classes.
• The FormField component, which was registered and bundled but unreachable.
• spatie/laravel-package-tools, which was required but never used.
• Fifteen npm dependencies, six of them copy-pasted from nova-field-map and never referenced.

Contributing

Nova is a commercial package, so a working checkout needs an auth.json in the project root carrying your Nova credentials. It is gitignored and export-ignored, so it is neither committed nor shipped in a distributed tarball.

composer install
npm install

dist/ is committed on purpose — the service provider serves the built assets from there, so any change under resources/ must ship with a rebuilt bundle.

What a pull request has to pass

composer lint     // Pint + PHPStan level 6
composer test     // Pest
npm run test      // Vitest
npm run build     // rebuild dist/ and commit it

composer check runs the lint and the Pest suite together. The suite is 164 Pest tests and 22 Vitest tests; new behaviour needs a test of its own.

Conventions

• PHP — Pint (laravel preset, declare(strict_types=1)), PHPStan level 6.
• JS and Vue — Prettier, <script setup> SFCs.
• The README carries no code samples. They live on this site, in docs/, which is the single source for them. A sample added here is covered by the Pest suite that owns the behaviour.
• Resolution stays framework-free. Nothing under src/Support, src/Results, src/Enums or src/Contracts may reference Laravel\Nova; tests/ArchTest.php enforces it. That is what keeps the colour, enum and threshold logic unit-testable without booting an application.
• Never interpolate a configured value into a class name or a style string. Colours are validated in Support\ColorResolver and bound as a style object — see Security for why.

Credits

• Oleg Khalin — the original nova4-indicator-field, which this package began as.
• Gabriele Sbaiz — the 2.0 rewrite and maintenance.
• All contributors.

Licence

The package is MIT licensed and always will be. Sponsorship buys maintenance time, not features. Nova itself is commercial and is not covered by this licence — a Laravel Nova licence is sold separately by Laravel.

The MIT License (MIT)

Copyright (c) Gabriele Sbaiz <gabriele@sbaiz.com>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.