PHPackages                             la-souris/filament-state-stepper - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. la-souris/filament-state-stepper

ActiveLibrary

la-souris/filament-state-stepper
================================

Filament v5 infolist component for Spatie ModelStates with transition-aware step ordering and status-aware labels.

v1.0.0(1mo ago)00MITPHP ^8.5

Since Jun 16Compare

[ Source](https://github.com/la-souris/package-filament-state-stepper)[ Packagist](https://packagist.org/packages/la-souris/filament-state-stepper)[ RSS](/packages/la-souris-filament-state-stepper/feed)WikiDiscussions Synced today

READMEChangelog (1)Dependencies (6)Versions (2)Used By (0)

Filament State Stepper
======================

[](#filament-state-stepper)

[![Tests](https://github.com/la-souris/filament-state-stepper/actions/workflows/tests.yml/badge.svg)](https://github.com/la-souris/filament-state-stepper/actions/workflows/tests.yml)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)

A Filament v5 infolist component that renders [Spatie ModelStates](https://github.com/spatie/laravel-model-states) 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
------------

[](#requirements)

- PHP 8.5+
- Filament v5
- Spatie Laravel Model States v2

Installation
------------

[](#installation)

```
composer require la-souris/filament-state-stepper
```

Register the plugin in your Filament panel provider:

```
use LaSouris\FilamentStateStepper\StateStepperPlugin;

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

Usage
-----

[](#usage)

### With Spatie ModelStates

[](#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

[](#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

[](#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

[](#customizing-colors)

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

### Hiding states

[](#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
-----------------------

[](#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
-------

[](#testing)

```
composer test
```

Credits
-------

[](#credits)

Inspired by [aureuserp/progress-stepper](https://github.com/aureuserp/progress-stepper/).

License
-------

[](#license)

MIT. See [LICENSE](LICENSE) for details.

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance92

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

37d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/930ca3b1756d00a63c8ff3363e81f16f961cf3ef79ff0c9d362670c36d97e456?d=identicon)[LauLaman](/maintainers/LauLaman)

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/la-souris-filament-state-stepper/health.svg)

```
[![Health](https://phpackages.com/badges/la-souris-filament-state-stepper/health.svg)](https://phpackages.com/packages/la-souris-filament-state-stepper)
```

###  Alternatives

[filament/filament

A collection of full-stack components for accelerated Laravel app development.

3829.6M3.9k](/packages/filament-filament)[filament/actions

Easily add beautiful action modals to any Livewire component.

1327.7M87](/packages/filament-actions)[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.8M48](/packages/spatie-laravel-pdf)[relaticle/flowforge

Flowforge is a lightweight Kanban board package for Filament that works with existing Eloquent models.

413106.5k10](/packages/relaticle-flowforge)[backstage/mails

View logged mails and events in a beautiful Filament UI.

16121.5k](/packages/backstage-mails)[codebar-ag/laravel-filament-json-field

A Laravel Filament JSON Field integration with CodeMirror support

1126.6k](/packages/codebar-ag-laravel-filament-json-field)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)