- How do I install leek/filament-header-filters in a Laravel Filament app?
- Run composer require leek/filament-header-filters, then add the HasHeaderFilters trait to each ListRecords page or any Livewire component that uses InteractsWithTable. Finally, add the package stylesheet to the panel theme registered with ->viteTheme(), placing the @import after Filament's theme.css import, and run npm run build. The package requires PHP 8.2+ and Filament v4 or v5.
- Does this package support Filament v3?
- No. Filament Header Filters supports Filament v4.x and v5.x only, alongside PHP 8.2 or newer. Filament v3 is not supported, so if your panel is still on v3 you would need to upgrade Filament first. Check the composer constraints before adding it to a mixed-version monorepo.
- Why are my header filters not showing or the header row looks broken?
- The most common cause is the missing CSS import. The package ships a stylesheet that must be imported into your panel's Vite theme after Filament's own theme import, and assets must then be rebuilt with npm run build (or npm run dev restarted). Without that import the header row renders visually broken rather than throwing an error, so check your theme entrypoint first.
- Do header filters work with Filament's existing filter indicators, reset action and session persistence?
- Yes. The HasHeaderFilters trait wires header filters into Filament's existing $tableFilters Livewire state rather than creating a parallel filtering system. Filter indicators, the reset action and session persistence therefore keep working exactly as they do for panel filters. There is no second source of truth for engineers or users to reason about.
- Which filters can I attach to a column header?
- Any BaseFilter works: SelectFilter dropdowns, date pickers, and custom Filter classes with multi-field schemas. A common pattern is a min/max range using a Filter with ->columns(2) and two numeric TextInputs, with the query scoping written in your own ->query() callback. Because query logic stays in your codebase, the package does not hide filtering behaviour in vendor code.
- Does ->headerFilter() respect deferFilters()?
- No. The package ignores deferFilters(), so header filters are always live and apply as soon as the user changes a value. That is usually fine for a single dropdown, but it means min/max numeric ranges and date ranges fire on every keystroke or pick. Test the interaction against your own tables before shipping range filters to production.
- What is the biggest risk of using this package with Filament upgrades?
- The package ships a patched copy of Filament's filament-tables::index Blade view in order to render the header filter row. Any Filament release that changes that view can break table rendering outright, and that failure can land on a routine composer update. Pin Filament in lockstep and keep a regression test that renders every table page so a broken view fails in CI rather than in staging.
- Is leek/filament-header-filters actively maintained and what happens if it stalls?
- It is MIT licensed with a single maintainer, around 16 stars and no known dependents, so there is little community base to absorb an abandoned project. It is a free port of filamentphp/filament#19432, which means upstream Filament may eventually ship native header filters and give you an exit path. The MIT licence also allows forking, but you should be comfortable patching a Blade view if that becomes necessary.
- Can I use it on tables that only have header filters?
- Yes, but tooling may complain. FilaCheck's missing-table-filters rule false-positives on header-filter-only tables, so you need a published config change to silence it, and Filament's FiltersLayout::Hidden is often used for those resources. Tables mixing header filters with a normal filter panel will show two filter surfaces, which needs UX sign-off.
- Is this a replacement for searchable(isIndividual: true) on Filament columns?
- It is a richer alternative rather than a strict replacement. Instead of a plain per-column search box, you attach a SelectFilter, date picker or custom range filter directly to the column header, giving exact-match and range filtering from the header row. Because it plugs into $tableFilters, it coexists with panel filters, so decide per table whether you want header filters, panel filters, or both.