A Laravel Nova filter that renders into clickable pills.

A simple Laravel Nova filter that renders into colorful clickable pills. This filter is very inspired by this other package, however we needed some extra features (like customizing the color of each pill) for client projects and that package seemed to not be maintained nor production ready, so we decided to make our own version of this filter.

Installation

You can install the package in to a Laravel app that uses Nova via composer:

composer require eolica/nova-pill-filter

Usage

Creating the filter

You may create a new pill filter manually and extending the Eolica\NovaPillFilter\PillFilter class:

namespace App\Nova\Filters;

use Illuminate\Http\Request;
use Eolica\NovaPillFilter\PillFilter;

final class MyPillFilter extends PillFilter
{
    public function apply(Request $request, $query, $value)
    {
        return $query;
    }

    public function options(Request $request)
    {
        return [];
    }
}

Or, even easier, using the following artisan command:

php artisan nova:pill-filter MyPillFilter

If you want to customize the "stub" the command uses to generate the filter class, you may use the following command to publish it:

php artisan nova:pill-filter-stubs

Next, we must register the filter within the filters method of our resource:

final class MyNovaResource extends Resource {

    public function filters(Request $request)
    {
        return [
            Filters\MyPillFilter::make(),
        ];
    }
}

Configuring the filter

By default multiple items can be selected, you can restrict it to a single item at time by using the single method

final class MyNovaResource extends Resource {

    public function filters(Request $request)
    {
        return [
            Filters\MyPillFilter::make()->single(),
        ];
    }
}

Also, the filter shows by default a "Clear" button when some item is active. When clicked, deactivates all items at once. If you want to hide the button you may use the hideClearButton method:

final class MyNovaResource extends Resource {

    public function filters(Request $request)
    {
        return [
            Filters\MyPillFilter::make()->hideClearButton(),
        ];
    }
}

If you want the "Clear" button to show, you may also change the text within by using the clearLabel method, mainly for translation purposes:

final class MyNovaResource extends Resource {

    public function filters(Request $request)
    {
        return [
            Filters\MyPillFilter::make()->clearLabel('Custom label'),
        ];
    }
}

Last, you may change the displaying mode of the filter, by default it wraps to show all pills at once, however you may change it to drag mode by using the draggable method:

final class MyNovaResource extends Resource {

    public function filters(Request $request)
    {
        return [
            Filters\MyPillFilter::make()->draggable(),
        ];
    }
}

Configuring the filter options

The most simple way is to return a key/value pair array, the key being the label displayed within the pill:

final class MyPillFilter extends PillFilter
{
    public function options(Request $request)
    {
        return [
            'Family'        => 'family',
            'Sea'           => 'sea',
            'Sports'        => 'sports',
            'City'          => 'city',
            'Eco'           => 'eco',
            'Countryside'   => 'countryside',
        ];
    }
}

You may customize each pill background color, text color, background color when active and text color when active, in this case the key of each option must be the value and the label text must be within the label key:

final class MyPillFilter extends PillFilter
{
    public function options(Request $request)
    {
        return [
            'family' => [
                'label'                 => 'Family',
                'color'                 => '#d53f8c', // Default '#3c4b5f'
                'backgroundColor'       => '#fbb6ce', // Default '#eef1f4'
                'colorActive'           => '#ffffff', // Default '#ffffff'
                'backgroundColorActive' => '#d53f8c', // Default '#4099de'
            ],
            'sea' => [
                'label'                 => 'Sea',
                'color'                 => '#3182ce',
                'backgroundColor'       => '#bee3f8',
                'colorActive'           => '#ffffff',
                'backgroundColorActive' => '#3182ce',
            ],
            'sports' => [
                'label'                 => 'Sports',
                'color'                 => '#e53e3e',
                'backgroundColor'       => '#fed7d7',
                'colorActive'           => '#ffffff',
                'backgroundColorActive' => '#e53e3e',
            ],
            ...
        ];
    }
}

Applying the values to the query

The filter will send you an array containing the values that are active.

final class MyPillFilter extends PillFilter
{
    public function apply(Request $request, $query, $values)
    {
        return $query->whereIn('lifestyle', $values); // $values is an array
    }
}

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security

If you discover a security vulnerability within this package, please send an email at [email protected] instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.