Decorated Column by ornio

• Installation
• Usage
  • Table columns
  • Infolist entries
• Badges
• Icons
• Dots
• Images
• Text
• Colors
• Trends
• Progress
• Pills
• Separator
• Closure parameters
• Testing
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

Decorate any text column or entry with rich prefixes and suffixes. Badges, dots, trends, progress bars and more, with no theme build needed.

DecoratedColumn and DecoratedEntry are Filament's TextColumn and TextEntry with a slot before and a slot after the text. A status, an avatar, or a trend can then sit next to the value it describes instead of taking a column of its own. The slots hold decorations of eight kinds, in any mix: badges, icons, dots, images, secondary text, colour samples, trends, and progress bars. Every decoration can have a tooltip, and every setter accepts a closure that receives the row's record. The views use inline styles and Filament's own fi-* classes, so there is no theme to build and no @source line to add.

use App\Models\Client;
use Filament\Support\Icons\Heroicon;
use Ornio\FilamentDecoratedColumn\BadgeDecoration;
use Ornio\FilamentDecoratedColumn\DecoratedColumn;
use Ornio\FilamentDecoratedColumn\IconDecoration;

DecoratedColumn::make('name')
    ->prefixDecorations([
        IconDecoration::make('type')->icon(Heroicon::OutlinedBriefcase)->label('Business'),
    ])
    ->suffixBadges([
        BadgeDecoration::make('vip')
            ->label('VIP')
            ->color('success')
            ->visible(fn (Client $record): bool => $record->is_vip),
    ]);

Each row shows the briefcase, an em dash, and the name. VIP rows add another em dash and a green badge.

#Installation

composer require ornio/filament-decorated-column

Requires PHP 8.2 or later and Filament 5.7 or later. Laravel discovers the service provider. There is no panel plugin to register, no config to publish, and no theme to build.

To change the markup, publish the views:

php artisan vendor:publish --tag="filament-decorated-column-views"

#Usage

#Table columns

DecoratedColumn extends TextColumn, so description(), searchable(), sortable(), wrap(), and the rest work unchanged. Add decorations with prefixDecorations() and suffixDecorations(), or their aliases prefixBadges() and suffixBadges(). All four take an array of decorations or a closure that returns one. The array can mix kinds, such as a DotDecoration next to a BadgeDecoration.

use App\Models\Client;
use Filament\Tables\Table;
use Ornio\FilamentDecoratedColumn\BadgeDecoration;
use Ornio\FilamentDecoratedColumn\DecoratedColumn;

public static function configure(Table $table): Table
{
    return $table->columns([
        DecoratedColumn::make('name')
            ->description(fn (Client $record): ?string => $record->registration_number)
            ->suffixBadges([
                BadgeDecoration::make('type')
                    ->label(fn (Client $record): string => $record->type->getLabel())
                    ->color(fn (Client $record): string => $record->type->getColor()),
            ])
            ->searchable()
            ->sortable(),
    ]);
}

Here type casts to an enum that implements Filament's HasLabel and HasColor contracts.

A bare icon in the prefix slot, driven by an enum that implements HasIcon:

use App\Models\Activity;
use Filament\Support\Enums\IconSize;
use Filament\Support\Icons\Heroicon;
use Ornio\FilamentDecoratedColumn\DecoratedColumn;
use Ornio\FilamentDecoratedColumn\IconDecoration;

DecoratedColumn::make('description')
    ->prefixDecorations([
        IconDecoration::make('type')
            ->icon(fn (Activity $record): Heroicon => $record->type->getIcon())
            ->size(IconSize::Large),
    ])
    ->wrap(),

#Infolist entries

DecoratedEntry extends TextEntry and takes the same methods.

use App\Models\Client;
use Filament\Schemas\Schema;
use Ornio\FilamentDecoratedColumn\BadgeDecoration;
use Ornio\FilamentDecoratedColumn\DecoratedEntry;

public static function configure(Schema $schema): Schema
{
    return $schema->components([
        DecoratedEntry::make('name')
            ->suffixBadges([
                BadgeDecoration::make('type')
                    ->label(fn (Client $record): string => $record->type->getLabel())
                    ->color(fn (Client $record): string => $record->type->getColor()),
            ]),
    ]);
}

Both work in any table or infolist, whether it sits in a panel or in a Livewire component outside one.

#Badges

BadgeDecoration::make('name') creates a badge. The name doubles as the default label: BadgeDecoration::make('hot') reads "Hot" and BadgeDecoration::make('is_paid') reads "Is paid".

Every method accepts a closure. See Closure parameters.

weight() and fontFamily() put Filament's fi-font-* class on the badge (fi-font-bold, fi-font-mono). Filament's stylesheet defines those classes for text items and links, not for badges, so they change a badge only where your theme styles .fi-badge.fi-font-*.

A hidden badge renders nothing. When every decoration in a slot is hidden, the slot's separator goes with it.

use App\Models\TeamMember;
use Filament\Support\Enums\IconPosition;
use Filament\Support\Icons\Heroicon;

BadgeDecoration::make('you')
    ->color('gray')
    ->tooltip('You cannot change your own role.')
    ->visible(fn (TeamMember $record): bool => $record->user_id === auth()->id()),

BadgeDecoration::make('paid')
    ->color('success')
    ->icon(Heroicon::OutlinedCheckCircle)
    ->iconPosition(IconPosition::After),

#Icons

IconDecoration::make('name') renders an icon with no badge around it.

On an icon, dot, text, or progress bar, the colour name goes into an inline style. A name holding anything but lowercase letters, digits, and hyphens draws gray instead, so a name returned by a closure can't inject CSS.

Without label() the icon is decorative and carries aria-hidden="true". That is right when the text beside it already says what the icon means. Give a label when the icon carries meaning on its own, and add tooltip() to show that meaning on hover too.

IconDecoration::make('type')
    ->icon(Heroicon::OutlinedBriefcase)
    ->label('Business')
    ->tooltip('Business client'),

#Dots

DotDecoration::make('name') renders a filled circle 0.5rem across, in a palette colour. Use it for a status. It has no size setting.

Without label() the dot is decorative and carries aria-hidden="true", as an unlabelled icon does. A screen reader can't announce a colour, so give a label when the dot shows a status that the text beside it doesn't.

use App\Models\Client;
use Ornio\FilamentDecoratedColumn\DotDecoration;

DecoratedColumn::make('name')
    ->prefixDecorations([
        DotDecoration::make('status')
            ->color(fn (Client $record): string => $record->is_active ? 'success' : 'gray')
            ->label(fn (Client $record): string => $record->is_active ? 'Active' : 'Inactive')
            ->tooltip(fn (string $state): string => $state),
    ]),

#Images

ImageDecoration::make('name') renders a small picture from a URL, such as an avatar, a logo, or a flag. The picture is cropped to fill its box, never stretched (object-fit: cover), and loads lazily.

Without label() the image is decorative and gets alt="", so screen readers skip it. That suits an avatar beside the person's name.

When the URL is null or an empty string, the image renders nothing, as if it were hidden. If nothing else in the slot renders, the separator goes too, so a row without a picture shows only its text.

use App\Models\User;
use Ornio\FilamentDecoratedColumn\ImageDecoration;

DecoratedColumn::make('name')
    ->prefixDecorations([
        ImageDecoration::make('avatar')
            ->image(fn (User $record): ?string => $record->avatar_url)
            ->circular(),
    ]),

#Text

TextDecoration::make('name') shows its label as secondary text, such as "(you)" after a name. As on a badge, the label is derived from the name when unset, and it is escaped. The text has no size setting: it takes the size of the text around it.

light-dark() follows the color-scheme: dark that a Filament panel sets in dark mode. Outside a panel, coloured text keeps its light-mode shade unless your page sets color-scheme itself.

weight() and fontFamily() set the text's font-weight and font-family inline. A weight is set as its number, such as 700 for FontWeight::Bold. A family uses the font your panel is configured with (the --font-family, --serif-font-family, and --mono-font-family variables that Filament sets), followed by generic families for pages outside a panel. A string that is not a FontWeight or FontFamily value is added as a class instead, for your theme to style.

use App\Models\Invoice;
use App\Models\TeamMember;
use Ornio\FilamentDecoratedColumn\TextDecoration;

TextDecoration::make('you')
    ->label('(you)')
    ->visible(fn (TeamMember $record): bool => $record->user_id === auth()->id()),

TextDecoration::make('overdue')
    ->color('danger')
    ->visible(fn (Invoice $record): bool => $record->is_overdue),

#Colors

ColorDecoration::make('name') shows a sample of a raw colour from your data, such as a product's hex code. The sample is a 1.25rem square with slightly rounded corners and a thin translucent gray border, so white and black samples stay visible.

The raw colour goes into an inline style, where HTML escaping doesn't stop CSS injection, so only these formats are accepted, in any letter case:

• #rgb, #rgba, #rrggbb, and #rrggbbaa.
• rgb(), rgba(), hsl(), hsla(), and oklch() holding only numbers, each with an optional %, deg, grad, rad, or turn unit. Commas, slashes, and plain spaces may separate them. A tab or a line break inside the parentheses gets the value rejected.

Any other value, such as a colour name like red, a var(), or null, renders nothing, as if it were hidden. The inherited color() is ignored, because the sample always shows the raw colour.

Without label() the sample is decorative and hidden from screen readers, which suits a sample next to the colour code it shows.

use App\Models\Product;
use Ornio\FilamentDecoratedColumn\ColorDecoration;

DecoratedColumn::make('color')
    ->prefixDecorations([
        ColorDecoration::make('sample')
            ->value(fn (Product $record): ?string => $record->color),
    ]),

#Trends

TrendDecoration::make('name') shows a change as an arrow and a signed number, coloured by direction:

• A rise shows an up arrow, a plus sign, and the success colour: +12.5%.
• A fall shows a down arrow, a minus sign (−, not a hyphen), and the danger colour: −3.2%.
• Zero shows in gray, with no arrow and no sign: 0.0%.

The direction is decided after rounding, so a change of 0.04 shows as a gray 0.0%, never as a green +0.0%.

The colour follows the direction, so the inherited color() is ignored. It uses the same shades as a text decoration: 600 in light mode and 400 in dark mode, or var(--gray-500) at zero.

The number ignores the app's locale. It always has a . decimal point and no thousands separator, as in +1234.5%. A null change, or one that is not a finite number (NAN or infinity), renders nothing, as if it were hidden.

Screen readers skip the arrow and read the signed number.

use App\Models\Account;
use Ornio\FilamentDecoratedColumn\TrendDecoration;

DecoratedColumn::make('revenue')
    ->suffixDecorations([
        TrendDecoration::make('revenue_change')
            ->value(fn (Account $record): ?float => $record->revenue_change),
    ]),

DecoratedColumn::make('churn_rate')
    ->suffixDecorations([
        TrendDecoration::make('churn_change')
            ->value(fn (Account $record): ?float => $record->churn_change)
            ->decimals(2)
            ->unit(' pp')
            ->inverse(),
    ]),

#Progress

ProgressDecoration::make('name') shows how close a value is to its maximum as a thin, partly filled bar. The track is 3.75rem wide and 0.375rem tall, with rounded ends.

The value is clamped between 0 and the maximum, so the fill never overflows the track, and aria-valuenow reports the clamped value. A maximum of zero or less shows an empty bar, and aria-valuemax reports it as 0. A null value renders nothing, as if it were hidden.

Without label() the bar is decorative and hidden from screen readers, which suits a bar beside the figure it draws.

use App\Models\Account;
use Ornio\FilamentDecoratedColumn\ProgressDecoration;

DecoratedColumn::make('seats_used')
    ->suffixDecorations([
        ProgressDecoration::make('seats')
            ->value(fn (Account $record): int => $record->seats_used)
            ->max(fn (Account $record): int => $record->seat_limit)
            ->color(fn (Account $record): string => $record->seats_used >= $record->seat_limit ? 'danger' : 'primary'),
    ]),

#Pills

asPills() on the column or entry rounds every badge in both slots. It accepts a closure. A single badge overrides it with isPill() or isPill(false).

DecoratedColumn::make('name')
    ->asPills()
    ->suffixBadges([
        BadgeDecoration::make('new'),
        BadgeDecoration::make('draft')->isPill(false),
    ]);

#Separator

separator() sets the mark between the text and a non-empty slot. It takes a string or a closure. By default the mark is an em dash (—) at 37.5% opacity. Calling separator() with no argument sets a comma, because the method's own default is ','. A blank string removes the mark and widens the gap between slot and text from 0.25rem to 0.5rem.

DecoratedColumn::make('name')->separator('')->suffixBadges([/* ... */]);
DecoratedColumn::make('name')->separator('·')->suffixBadges([/* ... */]);

The separator is output as raw HTML, so entities work and user input must never go there.

Text set with prefix() or suffix() still renders, between the separator and the column text.

On TextColumn and TextEntry, separator() means something else: it splits a string state into a list on that character. DecoratedColumn and DecoratedEntry replace that method, and the inherited getSeparator() stays null, so the state is never split. With separator(','), a name like Smith, John stays one value. If you need a list, give the column an array state.

#Closure parameters

Every closure on a decoration can ask for these parameters by name:

• $record: the row's Eloquent model, or null when the column has none.
• $state: the decoration's own resolved label, not the column's state.
• $livewire: the Livewire component that owns the table or infolist.

Parameters match by name, so call them exactly that. The type hint can be your model class: fn (Client $record). Other type-hinted parameters resolve from the container, as in any Filament closure.

The data setters work the same way: image() on an image, value() on a colour sample, trend, or progress bar, and max() on a progress bar. None of them receives the column's state, so read the data from $record, as the examples above do.

$state is for color(), icon(), tooltip(), visible(), value(), and the like. Don't request it inside label(): the label is what $state resolves to, so the closure would call itself. Inside weight() and fontFamily(), Filament's own traits inject $state as null.

use App\Models\Invoice;

BadgeDecoration::make('status')
    ->label(fn (Invoice $record): string => $record->status->getLabel())
    ->color(fn (string $state): string => $state === 'Overdue' ? 'danger' : 'gray'),

#Testing

composer test

#Changelog

See CHANGELOG for recent changes.

#Contributing

See CONTRIBUTING.

#Security Vulnerabilities

To report a security vulnerability, follow our security policy.

#Credits

• Flamur Mavraj
• All Contributors

#License

The MIT License (MIT). Please see License File for more information.