README

A Filament v5 infolist component that renders Spatie ModelStates as a visual step indicator. It automatically derives step order from AllowTransition attributes, resolves labels and icons from Filament contracts, and supports status-aware coloring for completed, current, upcoming, and error states.

Requirements

PHP 8.5+
Filament v5
Spatie Laravel Model States v2

Installation

composer require la-souris/filament-state-stepper

use LaSouris\FilamentStateStepper\StateStepperPlugin;

$panel->plugin(StateStepperPlugin::make());

Usage

With Spatie ModelStates

Pass your state base class to stateClass(). The component will automatically resolve the step order from AllowTransition attributes, starting at the DefaultState, and derive labels and icons from HasLabel and HasIcon contracts.

use LaSouris\FilamentStateStepper\Infolists\Components\StateStepper;

StateStepper::make('status')
    ->stateClass(OrderState::class)
    ->completedStates(fn ($record) => $record->getCompletedStates())
    ->errorStates(['cancelled']);

With manual options

StateStepper::make('status')
    ->options([
        'draft' => 'Draft',
        'review' => 'In Review',
        'approved' => 'Approved',
    ])
    ->icons([
        'draft' => 'heroicon-o-pencil',
        'review' => 'heroicon-o-eye',
        'approved' => 'heroicon-o-check-circle',
    ])
    ->completedStates(['draft'])
    ->errorStates(['rejected']);

Status-aware labels

Implement the HasStepperLabel contract on your state classes to display different labels depending on step status:

use LaSouris\FilamentStateStepper\Contracts\HasStepperLabel;
use Filament\Support\Contracts\HasLabel;

class ProcessingState extends OrderState implements HasStepperLabel, HasLabel
{
    public function getLabel(): string
    {
        return 'Processed';        // shown when completed
    }

    public function getCurrentLabel(): string
    {
        return 'Processing...';    // shown when current
    }

    public function getUpcomingLabel(): string
    {
        return 'Processing';       // shown when upcoming
    }
}

Customizing colors

StateStepper::make('status')
    ->stateClass(OrderState::class)
    ->completedColor('info')
    ->currentColor('primary')
    ->upcomingColor('gray')
    ->errorColor('danger');

Hiding states

Conditionally hide steps from the visual display:

StateStepper::make('status')
    ->stateClass(OrderState::class)
    ->hideStatesFor(fn ($record) => $record->isCancelled() ? [] : ['cancelled']);

How step ordering works

The component reads AllowTransition attributes from the state base class and builds a directed graph. Starting from the DefaultState, it walks the graph preferring non-terminal states (the "happy path") first. Terminal states (those without outgoing transitions) are appended at the end. When a terminal state is the current state, it displays as "completed" rather than "current".

Testing

composer test

Credits

Inspired by aureuserp/progress-stepper.

License

MIT. See LICENSE for details.

la-souris / filament-state-stepper

Maintainers

Package info

Statistics

Security