Filters ​

Overview ​

Nova ships with several filter types; however, sometimes you may need a filter type that isn't provided out of the box. For this reason, Nova allows you to build custom filters.

Defining Filters ​

Custom filters may be generated using the nova:custom-filter Artisan command. By default, all new filters will be placed in the nova-components directory of your application. When generating a filter using the nova:custom-filter command, the filter name you pass to the command should follow the Composer vendor/package format. So, if we were building an age-range filter, we might run the following command:

php artisan nova:custom-filter acme/age-range

When generating a filter, Nova will prompt you to install the filter's NPM dependencies, compile its assets, and update your application's composer.json file. All custom filters are registered with your application as a Composer "path" repository.

Nova filters include all of the scaffolding necessary to build your filter. Each filter even contains its own composer.json file and is ready to be shared with the world on GitHub or the source control provider of your choice.

Registering Filters ​

Nova filters may be registered in your resource's filters method. This method returns an array of filters available to the resource. To register your filter, add your filter to the array of filters returned by this method:

use Acme\AgeRange\AgeRange;

/**
 * Get the filters available for the resource.
 *
 * @param  \Laravel\Nova\Http\Requests\NovaRequest  $request
 * @return array
 */
public function filters(NovaRequest $request)
{
    return [
        new AgeRange,
    ];
}

Alternatively, you may use the make method to instantiate your filter:

use Acme\AgeRange\AgeRange;

/**
 * Get the filters available for the resource.
 *
 * @param  \Laravel\Nova\Http\Requests\NovaRequest  $request
 * @return array
 */
public function filters(NovaRequest $request)
{
    return [
        AgeRange::make(),
    ];
}

Any arguments passed to the make method will be passed to the constructor of your filter.

Building Filters ​

Each filter generated by Nova includes its own service provider and "filter" class. Using the age-range filter as an example, the filter class will be located at src/AgeRange.php.

The filter's service provider is also located within the src directory of the filter, and is registered in your filter's composer.json file so that it will be auto-loaded by the Laravel framework.

The Filter Vue Component ​

When Nova generates your filter, it creates a resources/js/components/Filter.vue Vue component. This component contains the template and logic for your filter when it is displayed in the filter dropdown menu. By default, the component displays a simple select filter component, along with the needed code for updating the filter's state.

Managing Filter State ​

Custom Nova filters use Vuex to manage their state. By default, your filter's Vue component stub contains the basic logic necessary to update the filter's current state. When modifying your filter's component, you should make sure the changes are committed to the Vuex store when your filter's "selected" value changes:

handleChange(event) {
    this.$store.commit('updateFilterState', {
        filterClass: this.filterKey,
        value: event.target.value,
    })

    this.$emit('change')
}

Assets ​

When Nova generates your filter, resources/js and resources/css directories are generated for you. These directories contain your filter's JavaScript and CSS.

Registering Assets ​

Your Nova filter's service provider registers your filter's compiled assets so that they will be available to the Nova front-end:

use Laravel\Nova\Nova;
use Laravel\Nova\Events\ServingNova;

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
    Nova::serving(function (ServingNova $event) {
        Nova::script('age-range', __DIR__.'/../dist/js/filter.js');
        Nova::style('age-range', __DIR__.'/../dist/css/filter.css');
        Nova::translations(__DIR__.'/../resources/lang/en/age-range.json');
    });
}

Compiling Assets ​

Your Nova filter contains a webpack.mix.js file, which is generated when Nova creates your filter. You may build your filter using the NPM dev and prod commands:

# Compile your assets for local development...
npm run dev

# Compile and minify your assets...
npm run prod

In addition, you may run the NPM watch command to auto-compile your assets when they are changed:

npm run watch