Weave Code
Progress Stepper Laravel Package
aureuserp/progress-stepper
A Filament v5 plugin that renders workflow state as an interactive arrow stepper in forms or a read-only status bar in infolists. Four overridable state colors, error states, enum support, icons, three sizes and horizontal or vertical layouts for business apps tracking orders and projects.
At a glance
Frequently asked questions about Progress Stepper
- How do I install aureuserp/progress-stepper in a Laravel app?
- Run composer require aureuserp/progress-stepper, then register the plugin in your Filament panel provider, typically with ->plugin(ProgressStepperPlugin::make()) inside the panel() method. There are no migrations and no service providers of your own to write, and publishing the views is optional and only needed if you want to change the markup. Integration typically takes under a day for a developer already comfortable with Filament.
- Which Laravel and Filament versions does progress-stepper require?
- The package targets Filament v5 panels, which means a modern Laravel application and PHP 8.2 or newer as the typical baseline. It is a Filament panel UI component and has no application outside Filament, so a plain Laravel app gains nothing from installing it. Check the package composer.json for the exact Filament constraint before adopting, because a Filament minor release has broken it before.
- How do I show a workflow stepper in a Filament form versus an infolist?
- In a form schema you use the ProgressStepper component, which extends Filament's ToggleButtons and renders an interactive arrow stepper the user can click. In an infolist you use the matching entry, which renders a read-only status bar for view and detail pages. Both share the same state colours, sizes, direction and enum options, so the same workflow can appear on edit and read-only screens.
- Can I drive the stepper steps from a PHP backed enum?
- Yes. Call optionsFromEnum(MyStatus::class) with a backed enum and the stepper derives step labels, icons and colours from it automatically. That keeps the workflow definition in one place instead of duplicating an options array in every form and infolist. You can still pass a plain array of options when an enum is overkill.
- How do I override the completed, current, upcoming and error colours?
- Four state colours are exposed, completed, current, upcoming and error, and each can be overridden on the component. Use errorStates([...]) to flag specific states as danger so failed or rejected steps render in the error colour. Calling markCompletedUpToCurrent() paints every step before the active one as completed so you do not have to compute that yourself.
- What sizes, directions and layouts does the stepper support?
- There are three sizes (sm, md, lg) and two directions (horizontal and vertical via Direction::Vertical), plus type-safe enums such as Size::Large and ConnectorShape::Chevron. Plain strings still work for backwards compatibility. The vertical layout is useful in narrow sidebars or on admin screens where horizontal space is tight.
- Is aureuserp/progress-stepper safe to use in production after the Filament 5.9 fatal error?
- Version 1.0.2 fixed a hard break where ProgressStepper::size() collided with the size() API that ToggleButtons gained in Filament 5.9, causing a PHP fatal that try/catch cannot intercept. Because the component inherits from a Filament base class, it inherits upstream's method surface and can break on Filament minor releases, not just majors. Pin Filament to a tested range, run the stepper's tests in your own CI, and treat Filament upgrades as a deliberate change. Also weigh the single-maintainer bus factor before depending on it in a critical panel.
- Why does an unsupported size like "large" silently render at medium?
- Unsupported sizes fall back to md instead of throwing, so a typo such as 'lg' or 'large' renders at medium with no diagnostic. For a cosmetic component that is a defensible trade-off, but it removes the cheapest signal that your usage has drifted. Prefer the Size enum, for example Size::Large, so mistakes surface at the type level instead of as a quiet visual regression.
- How do I test the progress stepper in my own Laravel test suite?
- The package ships with its own test suite and the README documents how to run it. In your app, exercise the stepper through Filament's form and infolist testing helpers or Livewire component tests, asserting that the expected states, colours and enum-derived options render. If you support multiple Filament minor versions, add a regression test covering the size() signature with the Size enum, null, a valid string and an invalid string.
- What are the alternatives to this package if I am not using Filament?
- If your admin surface is not Filament-native, do not adopt this package, because a plain Blade and Tailwind stepper is a few hours of work and carries zero upstream coupling. If you want the package but worry about maintenance, review LICENSE.md to confirm you may fork and vendor it internally, then vendor the source so an abandoned upstream cannot break your panel. Inside Filament panels it complements rather than overlaps the built-in wizard and form components.
Weaver
How can I help you explore Laravel packages today?