Filter Builder

A compact filtering UI for any list or table: active filters render as removable chips, and an Add filter popover walks the user through picking a field, an operator valid for that field's type, and a typed value. On every change it emits a normalized [{field, op, value}] array — ready to drive a server query or a client-side filter.

It composes form inputs behind a small Alpine state machine; there is no new styling vocabulary to learn. Each field declares its type, and the popover offers only the operators and value editor that make sense for it (no contains on a number, no free-text on a boolean).

#Basic Usage

Pass an array of field definitions. Each is {key, label, type} with optional options (for select) and custom operators.

<x-wirekit::filter-builder :fields="[
    ['key' => 'status', 'label' => 'Status', 'type' => 'select', 'options' => [
        ['value' => 'open', 'label' => 'Open'],
        ['value' => 'closed', 'label' => 'Closed'],
    ]],
    ['key' => 'title', 'label' => 'Title', 'type' => 'text'],
    ['key' => 'amount', 'label' => 'Amount', 'type' => 'number'],
    ['key' => 'due', 'label' => 'Due date', 'type' => 'date'],
]" />

#With Active Filters

Seed the bar with existing filters via :value. Each filter is a chip — click it to edit, or use the × to remove.

<x-wirekit::filter-builder
    :fields="[
        ['key' => 'status', 'label' => 'Status', 'type' => 'select', 'options' => [
            ['value' => 'open', 'label' => 'Open'],
            ['value' => 'closed', 'label' => 'Closed'],
        ]],
        ['key' => 'priority', 'label' => 'Priority', 'type' => 'select', 'options' => [
            ['value' => 'low', 'label' => 'Low'],
            ['value' => 'high', 'label' => 'High'],
        ]],
        ['key' => 'amount', 'label' => 'Amount', 'type' => 'number'],
    ]"
    :value="[
        ['field' => 'status', 'op' => 'is', 'value' => 'open'],
        ['field' => 'amount', 'op' => 'gt', 'value' => 1000],
    ]"
/>

#With Search

Set searchable to add a free-text box alongside the chips — handy when the list also supports keyword search. The box dispatches a bubbling search-change event with the current term (independent of the structured filters), so you can bind it on its own: x-on:search-change="$wire.set('q', $event.detail.value)".

<x-wirekit::filter-builder
    searchable
    search-placeholder="Search orders…"
    :fields="[
        ['key' => 'status', 'label' => 'Status', 'type' => 'select', 'options' => [
            ['value' => 'paid', 'label' => 'Paid'],
            ['value' => 'refunded', 'label' => 'Refunded'],
        ]],
        ['key' => 'total', 'label' => 'Total', 'type' => 'number'],
    ]"
/>

#With A Result Count

The status slot sits below the chips inside an aria-live region — perfect for a result count that updates as filters change.

<x-wirekit::filter-builder
    :fields="[
        ['key' => 'role', 'label' => 'Role', 'type' => 'select', 'options' => [
            ['value' => 'admin', 'label' => 'Admin'],
            ['value' => 'member', 'label' => 'Member'],
        ]],
        ['key' => 'active', 'label' => 'Active', 'type' => 'bool'],
    ]"
    :value="[['field' => 'role', 'op' => 'is', 'value' => 'member']]"
>
    <x-slot:status>42 members match</x-slot:status>
</x-wirekit::filter-builder>

#Field Definitions

Each entry in fields describes one filterable column:

#Operators By Type

The popover offers these operators automatically; override per field with operators:

#The Emitted Value

On every add / edit / remove / clear, filter-builder emits the normalized array two ways:

1. A bubbling filter-change event with detail.filters.
2. A JSON string written to a hidden input (so wire:model and plain forms both work).

{{-- 1. Bind the JSON bridge straight to a Livewire property --}}
<x-wirekit::filter-builder :fields="$fields" wire:model.live="filtersJson" />

// 2. Decode the JSON the bridge writes, then apply it to your query
public string $filtersJson = '[]';

public function rows()
{
    $filters = json_decode($this->filtersJson, true) ?: [];

    return collect($filters)->reduce(function ($query, $f) {
        // 3. Map (field, op, value) onto your query builder
        return match ($f['op']) {
            'contains' => $query->where($f['field'], 'like', "%{$f['value']}%"),
            'gt'       => $query->where($f['field'], '>', $f['value']),
            'is'       => $query->where($f['field'], $f['value']),
            default    => $query,
        };
    }, Order::query())->get();
}

Prefer events? Listen for filter-change and set the property yourself:

{{-- 4. Event-driven alternative — receive the array directly --}}
<x-wirekit::filter-builder
    :fields="$fields"
    x-on:filter-change="$wire.set('filters', $event.detail.filters)"
/>

#Livewire Integration

<x-wirekit::filter-builder> keeps its active filters in internal state seeded from the value prop, so when binding with Livewire pass the bound property as :value alongside wire:model to seed the initial filter rows:

<x-wirekit::filter-builder wire:model.live="filters" :value="$filters" :fields="$fields" />

Without :value the builder starts with no filter rows until the user adds one; wire:model keeps it in sync afterward. This is the framework-agnostic seeding pattern WireKit's stateful controls share — it works in plain Blade forms too.

#Props

#Accessibility

• Each chip is a button pair: the body opens the edit popover, the × removes the filter. Both are keyboard reachable and carry a descriptive aria-label ("Edit filter: Status is Open", "Remove filter: Status is Open").
• The add-filter trigger exposes aria-haspopup="dialog" and aria-expanded.
• The popover is a role="dialog" labeled by its heading. Opening it moves focus to the field selector; Escape, Cancel, and Apply return focus to the trigger. Clicking outside closes it without stealing focus back.
• Every popover control (field / operator / value) is a labeled form element.
• Wrap the status slot's result count in your own aria-live context (the slot is already inside a polite live region) so screen-reader users hear the count change.

#Keyboard Interaction

#Design Tokens

#Customization

Override the labels and the search default without publishing views via config/wirekit.php:

'components' => [
    'filter-builder' => [
        'searchable' => true,
        'search-placeholder' => 'Search records…',
        'add-label' => 'Add condition',
    ],
],

#Further Reading

• WAI-ARIA Authoring Practices — Dialog (Modal)
• Livewire — Data binding