Grid Filter Bar
The filter bar sits above an admin list. It holds a search box, a toggle for the filter panel, a clear button, and the filter fields from the grid form. The generated list prints it with one line, so you only add fields and handlers for your data.
<x-filter-bar :form="$form" :open="$showFilters"></x-filter-bar>Where the Fields Come From
The bar reads the grid form. The generated ProductGridForm defines two namespaces, and each one maps to a part of the bar:
search: the search box. The field*is the text input, so its name issearch/*.filter: the fields in the filter panel.
A field appears in the panel only when its namespace is filter. Add a filter field by adding a method with #[NS('filter')]:
// ProductGridForm.php
#[FormDefine]
#[NS('filter')]
public function filter(Form $form): void
{
$form->add('product.state', ListField::class)
->label($this->trans('unicorn.field.state'))
->option($this->trans('unicorn.select.placeholder'), '')
->registerFromEnums(BasicState::class, $this->lang)
->onchange('this.form.submit()');
$form->add('product.category_id', ListField::class)
->label('Category')
->option('Books', 1)
->option('Games', 2)
->onchange('this.form.submit()');
}The onchange('this.form.submit()') call sends the form when the value changes, so the list refreshes without a button.
WARNING
A filter field only changes the form. The list still needs a handler that turns the value into a condition. Add one with addFilterHandler(), as described in Custom Filter Rules.
Layout of the Panel
The bar has two rows. The top row holds the toggle, clear, and search controls. The panel below holds the filter fields:
Fields without a fieldset print in the first group. A field in a fieldset prints under the fieldset's title, and its label floats inside the input. Declare a fieldset with #[Fieldset] and a title:
#[FormDefine]
#[NS('filter')]
#[Fieldset('advanced', 'Advanced')]
public function advancedFilter(Form $form): void
{
$form->add('start_date', TextField::class)
->label('Created from')
->attr('type', 'date')
->onchange('this.form.submit()');
$form->add('end_date', TextField::class)
->label('Created to')
->attr('type', 'date')
->onchange('this.form.submit()');
}The panel opens by itself when the list has active filters, so the user sees the values that shape the list.
Props and Slots
The component takes these props. Set them as attributes, using kebab-case names:
{{-- Default: search, toggle, clear, and the filter panel --}}
<x-filter-bar :form="$form" :open="$showFilters"></x-filter-bar>
{{-- Keep the panel and buttons, but hide the search box --}}
<x-filter-bar :form="$form" :search-block="false"></x-filter-bar>
{{-- Hide the filter panel and its toggle button --}}
<x-filter-bar :form="$form" :filter-block="false"></x-filter-bar>
{{-- Replace the search box with your own HTML --}}
<x-filter-bar :form="$form" :search-block="$mySearch"></x-filter-bar>
{{-- Search a different field (it must be in the search namespace) --}}
<x-filter-bar :form="$form" search-input="search/product.title"
size="sm">
</x-filter-bar>
{{-- Open the panel for this page --}}
<x-filter-bar :form="$form" :open="true"></x-filter-bar>
{{-- Bind the bar to another Alpine store named "list" --}}
<x-filter-bar :form="$form" store="list"></x-filter-bar>The props have these effects:
open: opens the panel on load. The generated list sets it from$showFilters.search-block:nullby default.falsehides the search box, and a string prints that HTML instead.filter-block:nullby default.falsehides the panel and the toggle. A string prints that HTML as the panel.search-input: the form field path for the search box. The default issearch/*.size:smorlgfor the input group and buttons.store: the Alpine store that the bar'sx-datareads.
Two slots add content to the top row:
<x-filter-bar :form="$form" :open="$showFilters">
{{-- Left side, after the toggle and clear buttons --}}
<x-slot name="start">
<a href="{{ $nav->to('product_edit') }}"
class="btn btn-primary">
New Product
</a>
</x-slot>
{{-- Right side of the top row --}}
<x-slot name="end">
<span class="text-muted">
{{ $pagination->getTotal() }} items
</span>
</x-slot>
</x-filter-bar>The start and end slots print their content as HTML without escaping. Escape any user-supplied value with inside the slot, as the example does with the pagination total.
INFO
If filter-block is a string, the toggle button still shows, and it opens the custom HTML. The panel stays hidden until the user clicks it.
JavaScript Behavior
The bar uses the Alpine store grid, which useGridComponent() creates in the generated list script. Its methods handle the toggle, the clear button, and form submission:
- Toggle: the button flips
open. A watcher callsgrid.toggleFilters(), which slides the panel up or down. - Clear: the button calls
$store.grid.clearFilters($refs.filterbar). It empties every input and select in the bar, then submits the form. - Search: the search button submits the form, and so does pressing Enter in the search box.
- Filter fields: each
onchangehandler submits the form.
Use the store from your own buttons:
<button type="button"
class="btn btn-outline-secondary"
@click="$store.grid.sendFilter($event, 'GET')">
Apply
</button>WARNING
clearFilters() clears every input inside the bar. That includes the search box and any input you put in the start or end slot. Keep inputs that must survive a clear outside the bar.
INFO
The clear button always reads $store.grid. The store prop changes only the bar's own x-data, so renaming the store breaks the clear button.
Opening the Panel for Search Results
The generated list opens the panel only when a filter value is set. The isFiltered() method accepts the search text too, so the panel can open for a search:
// ProductListView.php
$showFilters = $this->isFiltered($filter, $search['*'] ?? '');TIP
Pass the search text as the second argument. Otherwise a user who searches for a product sees results but a closed filter panel.
Styling the Filter Bar
Unicorn does not ship CSS for the filter bar. It uses Bootstrap 5 utility classes, so you style it with your own CSS or with a theme.
Pass extra classes or attributes to the component. They are added to the root element, which already has c-filter-bar and mb-4:
<x-filter-bar :form="$form" :open="$showFilters"
class="p-3 bg-light rounded my-filter-bar"
id="product-filters">
</x-filter-bar>To change the markup, override the layout in your @theme folder. Copy views/ui/bootstrap5/grid/filter-bar.blade.php to views/theme/grid/filter-bar.blade.php, then edit the copy. Unicorn's @filter-bar alias then renders your file. For how theme folders work, see Theming.
WARNING
Keep the Alpine attributes in the copied file: x-data, x-init, the x-ref attributes (filterbar and filterForm), and the $store.grid calls. Removing or renaming them breaks the toggle and the clear button.