Column Filters

This section covers PowerGrid Column Filters.

Here you will find:

Introduction

The Search and Filter features are especially useful for when dealing with large tables. Rather than imposing limitations on the displayed data, users can have the freedom to choose which data they want to see.

In addition to the Global Search Input, PowerGrid offers customizable Column Filters that enable users to selectively exclude rows that do not meet specific criteria based on column values.

Activating Filters

Filters are registered inside the method filters() in your Table Component class.

To enable a new Column Filter, add a call to a Filter Facade, indicating in the parameter $column the Column to display the Filter. Then, proceed to configure the Filter by chaining its configuration methods.

If your Column is connected to a Custom Field, you must pass the Field to the parameter $field, indicating the data source for the filtering query.

Example:

php

// app/Livewire/DishTable.php

use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Facades\Filter;

class DishTable extends PowerGridComponent
{
    public function filters(): array
    {
        return [
            Filter::inputText('name')->placeholder('Dish Name'),

            Filter::boolean('in_stock')->label('In Stock', 'Out of Stock'),

            Filter::number('price_BRL', 'price')->thousands('.')
            ->decimal(','),
        ];
    }
}

🚀 See it in action

See an interactive example using Filters.

Filter Position

To configure PowerGrid's Filter display position, visit Filter Configuration section.

If you want to configure it individually per component, use Laravel's config() helper in your component's boot() method.

In this example, the filters are set to "outside" position exclusively for this component.

php

// app/Livewire/DishTable.php

use PowerComponents\LivewirePowerGrid\PowerGridComponent;

class DishTable extends PowerGridComponent
{
    public function boot(): void
    {
        config(['livewire-powergrid.filter' => 'outside']);
    }
}

Expand/Collapse Outside Filters

When working with Outside Filters, you may want to initialize the filters in either an expanded or collapsed state.

To display expanded filters, simply declare the property $showFilters as true in your Components class.

php

// app/Livewire/DishTable.php

use PowerComponents\LivewirePowerGrid\PowerGridComponent;

class DishTable extends PowerGridComponent
{
    public bool $showFilters = true;
}

Standard Filters

Here you can find PowerGrid Standard Filters.

Text Filter

Includes text input and a dropdown menu with text search options in the chosen column header.

By default, the filter has all searching options enabled. To customize the available options, see the method ->operators() below.

Example:

php

use PowerComponents\LivewirePowerGrid\Facades\Filter;

public function filters(): array
{
    return [
       Filter::inputText('name', 'name')
          ->operators(['contains', 'is', 'is_not']),
    ];
}

Input Filter Methods

Here you can find all configuration methods available for the Text Filter.

operators(array $operators)

Configures input text search options.

The parameter $operator accepts the following items:

plain

contains, contains_not, 
is, is_not, 
starts_with, ends_with, 
is_empty, is_not_empty, 
is_null, is_not_null, 
is_blank, is_not_blank

Boolean Filter

Includes a dropdown menu containing the options: "All", "true" and "false" in the chosen column header.

To customize the labels, see the ->label() method below.

Example:

php

use PowerComponents\LivewirePowerGrid\Facades\Filter;

public function filters(): array
{
    return [
        Filter::boolean('in_stock')
            ->label('yes', 'no'),
    ];
}

Boolean Filter Methods

Here you can find all configuration methods available for the Boolean Filter.

label(string $trueLabel, string $falseLabel)

Set the labels for true and false options (E.g, 'Active'/'Inactive').

Select Filter

Includes dropdown menu with options from a data source in the chosen column header.

Example:

php

use App\Models\Category;
use PowerComponents\LivewirePowerGrid\Facades\Filter;

public function filters(): array
{
    return [
        Filter::select('category_name', 'category_id')
            ->dataSource(Category::all())
            ->optionLabel('name')
            ->optionValue('id'),
    ];
}

Select Filter Methods

Here you can find all configuration methods available for the Select Filter.

datasource(Collection|array|Closure $collection)

Set a datasource to populate the select options.

optionValue(string $value)

Indicate the data source field to be displayed in options.

optionLabel(string $value)

Indicate the data source field to be used as each option ID.

Multi-Select Filter

Includes multi-select dropdown menu with options from a data source in the chosen column header.

PowerGrid supports TomSelect and SlimSelect to render a multi-select filter.

For this filter to work properly, you must install and configure either of these packages. For more information, refer to the section on Configuring TomSelect or Configuring SlimSelect.

Example:

php

use App\Models\Category;
use PowerComponents\LivewirePowerGrid\Facades\Filter;

public function filters(): array
{
    return [
        Filter::multiSelect('category_name', 'category_id')
            ->dataSource(Category::all())
            ->optionValue('id')
            ->optionLabel('name'),
    ];
}

Multi-Select Filter Methods

Here you can find all configuration methods available for the Multi-Select Filter.

datasource(Collection|array|Closure $collection)

Set a datasource to populate the select options.

optionValue(string $value)

Indicate the data source field to be displayed in options.

optionLabel(string $value)

Indicate the data source field to be used as each option ID.

Multi-Select Async Filter

If you don't want to load all together with the page loading, you may use this Async filter option. This filter works similarly to the Multi-Select Filter.

PowerGrid relies on TomSelect for loading Async data, you must install and configure it for this filter to work properly. For more information, refer to the section on Configuring TomSelect.

The example below returns data from an API endpoint.

PowerGrid TableRouteAPI Controller

php

// app/Livewire/DishTable.php

use PowerComponents\LivewirePowerGrid\Column;
use PowerComponents\LivewirePowerGrid\Facades\Filter;

class DishTable extends PowerGridComponent
{
    public function filters(): array
    {
        return [
            Filter::multiSelectAsync('category_name', 'category_id')
                ->url(route('category.index'))
                ->method('POST')
                ->parameters(['Pasta'])
                ->optionValue('id')
                ->optionLabel('name'),
        ],
    }
}

php

// routes/web.php
use App\Http\Controllers\Api\CategorySearch;

Route::post('category', CategorySearch::class)->name('category.index');

php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\Category;
use Illuminate\Contracts\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Http\Request;

class CategorySearch extends Controller
{
    public function __invoke(Request $request): Collection
    {
        return Category::query()
            ->select('id', 'name')
            ->orderBy('name')
            ->when($request->search,
                fn (Builder $query) => $query
                    ->where('name', 'like', "%{$request->search}%")
            )
            ->get();
    }
}

Multi-Select Async Filter Methods

Here you can find all configuration methods available for the Multi-Select Async Filter.

datasource(Collection|array|Closure $collection)

Set a datasource to populate the select options.

optionValue(string $value)

Indicate the data source field to be displayed in options.

optionLabel(string $value)

Indicate the data source field to be used as each option ID.

datasource(Collection|array|Closure $collection)

Set a datasource to populate the select options.

url(string $url)

Set the API URL to load Filter data.

method(string $method = 'get')

Set the HTTP Request method.

parameters(string $parameters = [])

Sets the Request Payload.

Enum Select Filter

Includes a dropdown menu with options using an Enum as data source in the chosen column header.

To display labels instead of case values, you can call the labelPowergridFilter() method inside your enum returning a string for each Enum case.

Example:

PowerGrid TableEnum Diet

php

// app/Livewire/DishTable.php

use App\Enums\Diet;
use PowerComponents\LivewirePowerGrid\Column;
use PowerComponents\LivewirePowerGrid\Facades\Filter;

class DishTable extends PowerGridComponent
{
    public function filters(): array
    {
        return [
            Filter::enumSelect('diet', 'dishes.diet') 
                ->datasource(Diet::cases())
                ->optionLabel('dishes.diet'),
        ];
    }

    public function columns(): array
    {
        return [
            Column::make('Dieta', 'diet', 'dishes.diet') 
            //...
        ];
    }
}

php

//app/Enums/Diet.php

enum Diet: int
{
    case ALL      = 0;
    case VEGAN    = 1;
    case CELIAC   = 2;

    public function labels(): string
    {
        return match ($this) {
            self::ALL         => "🍽️ All diets",
            self::VEGAN       => "🌱 Suitable for Vegans",
            self::CELIAC      => "🥜 Suitable for Celiacs",
        };
    }

    public function labelPowergridFilter(): string
    {
        return $this->labels();
    }
}

🚀 See it in action

See an interactive example using Enum Filter.

Enum Filter Methods

Here you can find all configuration methods available for the Enum Filter.

datasource(Collection|array $enumCases)

Set a datasource to populate the select options.

optionValue(string $value)

Indicate the data source field to be displayed in options.

optionLabel(string $value)

Indicate the data source field to be used as each option ID.

Datetime Picker Filter

Includes a Flatpickr date picker input in the chosen column header.

For this filter to work properly, you must install and configure Flatpickr. For more information, refer to the section on Configuring Flatpickr.

Example:

php

use PowerComponents\LivewirePowerGrid\Facades\Filter;

public function filters(): array
{
    return [
        Filter::datetimepicker('produced_at_formatted', 'produced_at'),
            ->params([
                    'timezone' => 'America/Sao_Paulo',
            ]),
    ];
}

Datetime Filter Methods

Here you can find all configuration methods available for Datetime filter.

params(array $params)

This method configures the Flatpick behavior. The options passed to the $params parameter must be in a key => value format.

Available options:

Parameter	value	Description
only_future	`bool`	Disallow selecting dates in the past.
no_weekends	`bool`	Disallow selecting weekend dates.
timezone	timezone	Parse the searched date with the specified timezone.

Date Picker Filter

Includes a Flatpickr date picker input in the chosen column header.

The Date Picker Filter functions similarly to the Date Time filter and shares all of its methods and configuration.

For more details, refer to the section on Datetime Picker Filter.

Example:

php

use PowerComponents\LivewirePowerGrid\Facades\Filter;

public function filters(): array
{
    return [
        Filter::datepicker('creation_date_formatted', 'creation_date'),
    ];
}

Dynamic Filter

Dynamic Filter lets you use an external component as a PowerGrid Filter. This is useful if you want to integrate packages like WireUI.

The example below renders the <x-select> component in the chosen column header.

php

// app/Livewire/DishTable.php

use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Facades\Filter;

class DishTable extends PowerGridComponent
{
    public function filters(): array
    {
        return [
            Filter::dynamic('in_stock', 'in_stock')
                ->component('select')
                ->attributes([
                    'class'           => 'min-w-[170px]',
                    'async-data'      => route('categories.index'),
                    'option-label'    => 'name',
                    'multiselect'     => false,
                    'option-value'    => 'id',
                    'placeholder'     => 'Test',
                    'wire:model.lazy' => 'filters.select.in_stock'
                ]),    
        ];
    }
}

🚀 See it in action

See an interactive example using Dynamic Filter.

component(string $component)

Set the component to be rendered.

attributes(array $attributes)

Passes attributes to the component.

Interdependent Filters

Many web applications require establishing hierarchical relationships between filters. The selection of the initial filter will directly impact the available options in the second filter. A common example is State > City filters.

To create a dependent filter in PowerGrid, you must chain the method depends() passing which fields this filter depends on. Next, you need to pass a closure containing the filter logic to the datasource() method.

In the example below, the City filter is set to filter by cities.id by default. However, if state_id is already selected, the condition in the City::query()->when() method is met, causing the City filter to search for the relationship state, with the selected State ID.

php

//app/View/Components/PowerGridTable.php

use Illuminate\Database\Eloquent\Builder;
use PowerComponents\LivewirePowerGrid\Facades\Filter;
use PowerComponents\LivewirePowerGrid\PowerGridComponent;

final class PowerGridTable extends PowerGridComponent
{
    public function filters(): array
    {
        return [
            Filter::select('state_name', 'states.id')
                ->dataSource(State::all())
                ->optionLabel('name')
                ->optionValue('id'),

            Filter::select('city_name', 'cities.id')
                ->depends(['state_id'])
                ->dataSource(
                    fn ($depends) => City::query()
                        ->when(
                            isset($depends['state_id']),
                            fn (Builder $query) => $query->whereRelation(
                                'state',
                                fn (Builder $builder) => $builder->where('id', $depends['state_id'])
                            )
                        )
                        ->get()
                )
                ->optionLabel('name')
                ->optionValue('id'),
        ];
    }
}

🚀 See it in action

See an interactive example using Filter Depends on a Table.

Filter Builder

Sometimes, you may need to customize a Filter functionality to deal with different data formats and improve user experience.

The Filter Builder lets you change the way a Filter works by interacting the query in a closure function.

For example, while calories is not a boolean field, "caloric or light" is a boolean choice. So, here we can use the Filter builder() method to interpret the given option and build a query on the calorie counting. In this example, the criteria of "is caloric?" selects between dishes of 300 kcal or more ("caloric"/true) and dishes under 300 kcal ("light"/false).

php

// app/Livewire/DishTable.php

use Illuminate\Database\Eloquent\Builder;
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Facades\Filter;

class DishTable extends PowerGridComponent
{
    public function filters(): array 
    {
        Filter::boolean('calories')
            ->label('Caloric', 'Light')
            ->builder(function (Builder $query, string $value) {
                $q = match ($value) {
                    default => ['operator' => '>=', 'calories' => 0],
                    'true'  => ['operator' => '>=', 'calories' => 300],
                    'false' => ['operator' => '<', 'calories' => 300],
                };

                return $query->where('calories', $q['operator'], $q['calories']);
            }),
    }
}

Additionally, you may use the collection() similarly when working with Collections:

php

use Illuminate\Support\Collection;

->collection(function (Collection $collection, mixed $value) {
    return $collection->where('some_field', '!=', $value);
})

🚀 See it in action

See an interactive example using Filter Builder.

Filter by Relationship

To filter by relationships, you must indicate your relationships in your Component's relationSearch() method.

Then, you may configure the filter with the filterRelation() method passing the field and the dataField.

php

// app/Livewire/DishTable.php

use Illuminate\Database\Eloquent\Builder;
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Facades\Filter;

class DishTable extends PowerGridComponent
{
    public function filters(): array
    {
        return [
            Filter::inputText('category_name')
                ->filterRelation('category', 'name')
        ];
    }
}

Custom Components

If you need to further customize your filters, you may render Blade Components with the Filter. This is useful when working with external packages like WireUI.

To render a component, chain the component() method to your Filter passing the Blade View and the attributes you may want to use in your component(E.g, wire:model or classes).

To use default PowerGrid attributes, just call $attributes->getAttributes() within your component.

Example:

php

// app/Livewire/DishTable.php

use Illuminate\Database\Eloquent\Builder;
use PowerComponents\LivewirePowerGrid\PowerGridComponent;
use PowerComponents\LivewirePowerGrid\Facades\Filter;

class DishTable extends PowerGridComponent
{
    public function filters(): array
    {
        return [
            Filter::boolean('in_stock')
                ->component('my-custom-select', [
                    'class' => 'p-2',
            ]),
        ];
    }
}

Your component will look something like this:

php

// resources/views/components/my-custom-select.blade.php

<div>
    @json($attributes->getAttributes())

    <input {{ $attributes->get('inputAttributes') }} />
</div>

Column Filters ​

Introduction ​

Activating Filters ​

Filter Position ​

Expand/Collapse Outside Filters ​

Standard Filters ​

Text Filter ​

Input Filter Methods ​

Boolean Filter ​

Boolean Filter Methods ​

Select Filter ​

Select Filter Methods ​

Multi-Select Filter ​

Multi-Select Filter Methods ​

Multi-Select Async Filter ​

Multi-Select Async Filter Methods ​

Enum Select Filter ​

Enum Filter Methods ​

Datetime Picker Filter ​

Datetime Filter Methods ​

Date Picker Filter ​

Dynamic Filter ​

Interdependent Filters ​

Filter Builder ​

Filter by Relationship ​

Custom Components ​

Column Filters

Introduction

Activating Filters

Filter Position

Expand/Collapse Outside Filters

Standard Filters

Text Filter

Input Filter Methods

Boolean Filter

Boolean Filter Methods

Select Filter

Select Filter Methods

Multi-Select Filter

Multi-Select Filter Methods

Multi-Select Async Filter

Multi-Select Async Filter Methods

Enum Select Filter

Enum Filter Methods

Datetime Picker Filter

Datetime Filter Methods

Date Picker Filter

Dynamic Filter

Interdependent Filters

Filter Builder

Filter by Relationship

Custom Components