> ## Documentation Index
> Fetch the complete documentation index at: https://docs.advancedtables.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Filters

> Give users quick access to table filters through clickable indicators with support for pinned and favorited filters.

![Quick filters](https://advancedtables.com/images/advanced-indicators.png)

> Important: Quick Filters is one of the biggest additions to Advanced Tables since it's initial launch and I'm very excited to be able to bring this functionality to Filament. However, since [additional configuration](/v5/features/quick-filters#enabling-quick-filters) is needed, there are still [outstanding features](/v5/features/quick-filters#specifying-favorite-filters-with-user-views-under-development) to be implemented, [known limitations](/v5/features/quick-filters#current-limitations-and-unknowns) exist, and there may be custom Filament implementations that haven't been accounted for, this feature is disabled by default. Please read all the instructions fully to know what is currently supported, what is under development, and what may not be supported. If you do find an issue, please reach out to me on discord our through email.

Quick Filters gives your users quick access to their filters through Filament's indicator system. When enabled, each indicator can be clicked on to access that filter's settings. In addition, filters can be favorited and "pinned" so they always appear, even when not active.

## Enabling Quick Filters

1. Enable Quick Filters

   Quick Filters is disabled by default. To enable, add `quickFiltersEnabled()` to your panel provider:

   ```php theme={null}
   AdvancedFilter::make()
       ->quickFiltersEnabled()
   ```

2. Compile assets

   After enabling be sure to run `npm run build` and `php artisan filament:upgrade`.

3. Update Custom Filter Classes

   Quick Filters automatically overrides any default Filament filters you have included in your resource or page. However, any *custom* filter classes that you have created that extends a Filament filter will need to be updated to use Advanced Table's versions. This can be easily accomplished by just updating your imported class with the plugins equivalent:

   ```php theme={null}
   - use Filament\Tables\Filters\Filter
   + use Archilex\AdvancedTables\Filament\Filter

   - use Filament\Tables\Filters\SelectFilter
   + use Archilex\AdvancedTables\Filament\SelectFilter

   - use Filament\Tables\Filters\TernaryFilter
   + use Archilex\AdvancedTables\Filament\TernaryFilter

   - use Filament\Tables\Filters\TrashedFilter
   + use Archilex\AdvancedTables\Filament\TrashedFilter
   ```

   Remember, you only need to override *custom* filter classes you have created. Filters used within Filament's resources and pages will be overridden automatically.

4. Add the AdvancedTables trait

   If you haven't already, [add the AdvancedTables trait](/v5/get-started/getting-started#adding-advanced-tables-to-your-table) to your table.

## Using Quick Filters

Once enabled, Quick Filters should work right out the box with minimal configuration. Just click on any indicator to see the form field(s) associated with that filter. Any adjustments to that filter will be immediately reflected in the table and synced to filament's filter form.

### Custom Filters with Multiple Form Fields

When implementing custom filters with multiple form fields in Filament, there are two main ways to display the indicator(s). You could display a single indicator that adapts according to the fields that are set, or you could have individual indicators for each field. As an example, take the following date filter examples which have two date fields, but display the indicator differently.

**Example 1 - Display as a single indicator:**

![Single indicator](https://advancedtables.com/images/single-indicator.png)

```php theme={null}
Filter::make('created_at')
    ->form([
        DatePicker::make('created_from'),
        DatePicker::make('created_until'),
    ])
    ->query(function (Builder $query, array $data): Builder {
        ...
    })
    ->indicateUsing(function (array $data): ?Indicator {                        
        if (($data['created_from'] ?? null) && (! ($data['created_until'] ?? null))) {
            return Indicator::make('Created from ' . Carbon::parse($data['created_from'])->toFormattedDateString());
        } 

        if ((! ($data['created_from'] ?? null)) && ($data['created_until'] ?? null)) {
            return Indicator::make('Created until ' . Carbon::parse($data['created_until'])->toFormattedDateString());
        } 

        if (($data['created_from'] ?? null) && ($data['created_until'] ?? null)) {
            return Indicator::make('Created between ' . Carbon::parse($data['created_from'])->toFormattedDateString() . ' and ' . Carbon::parse($data['created_until'])->toFormattedDateString());
        }

        return null;
    })
```

**Example 2 - Display as multiple indicators:**

![Multiple indicators](https://advancedtables.com/images/multiple-indicators.png)

```php theme={null}
Filter::make('published_at')
    ->form([
        DatePicker::make('published_from'),
        DatePicker::make('published_until'),
    ])
    ->query(function (Builder $query, array $data): Builder {
        ...
    })
    ->indicateUsing(function (array $data): array {                        
        $indicators = [];

        if ($data['published_from'] ?? null) {
            $indicators[] = Indicator::make('Published from ' . Carbon::parse($data['published_from'])->toFormattedDateString())
                ->removeField('published_from');
        }

        if ($data['published_until'] ?? null) {
            $indicators[] = Indicator::make('Published until ' . Carbon::parse($data['published_until'])->toFormattedDateString())
                ->removeField('published_until');
        }

        return $indicators;
    }),
```

Quick Filters supports both of these use cases. In the first example, only one indicator will be shown, but the form will include both fields. In the second, only the indicator's respective field will be displayed.

If you are using return types (and you should be) then Quick Filters will automatically detect how the indicators should be displayed. If you are not using return types, then you will need to be explicit about how Quick Filters should display your form fields using the `->multipleIndicators()` method:

**Example 1 - Display as a single indicator:**

```php theme={null}
Filter::make('created_at')
    ->multipleIndicators(false)
```

**Example 2 - Display as multiple indicators:**

```php theme={null}
Filter::make('created_at')`
    ->multipleIndicators()
```

> Note: Displaying indicators outside of these two examples (ie. a single indicator for all form fields, or a one-to-one field/indicator setup), is not currently supported. If you have a filter set up like this, please contact me.

### Favorite Filters

![Favorite filters](https://advancedtables.com/images/favorite-filters.png)

Quick Filters not only gives you quick access to applied filters, but also allows you to specify "favorite" filters which will always be displayed in the indicator bar, even when the filter is not active. You can make a filter a favorite by using the `->favorite()` method:

```php theme={null}
SelectFilter::make('brand')
    ->favorite()
```

> Note: Support for Filament's `->columns()` method on filters is coming soon.

### Limiting the Indicator labels

![Quick Filters](https://advancedtables.com/images/advanced-indicators.png)

Quick Filters also introduces the ability to limit the number of labels that are shown on a Select Filter. Since you now have easy access to filters through the indicator, it may not be necessary to pollute the indicator bar with an excessively long indicator. To limit the indicator labels you may use the `->limitIndicatorLabels()` method:

```php theme={null}
SelectFilter::make('brand')
    ->limitIndicatorLabels(3)
```

By default, once the limit is reached Filament's localized version of `& 3 more` will be displayed. However, you may change this by publishing and updating the plugin's language files and updating the `more_indicator_labels` value in the `advanced-tables.php` language file:

```php theme={null}
'indicators' => [
    'more_indicator_labels' => '+ :count', // display as "+ 4"
],
```

### Specifying Favorite Filters in Preset Views

If you are using [Preset Views](/v5/features/preset-views) you may configure which filters should be displayed as favorites using the `->defaultFavoriteFilters()` method:

```php theme={null}
'recentlyCreated' => PresetView::make()
    ->favorite()
    ->defaultFavoriteFilters(['created_at'])
    ->defaultFilters([
        'created_at' => [
            'created_from' => now()->startOfWeek()->toDateString(),
            'created_until' => now()->endOfWeek()->toDateString(),
        ],
    ])
```

> Note: When defining default favorite filters, the order of the filters will be determined by the order they are in listed in Filament's ->filters() array. Support for ordering by the order of the ->defaultFavoriteFilters() array is coming.

### Specifying Favorite Filters with User Views (Under Development)

User-specified favorite filters is currently under development and should be released soon. When released, your users will be able to favorite, rearrange, and even hide filters according to their needs and then save that configuration as a [User View](/v5/features/user-views).

### Deferring Quick Filters

The current implementation of Quick Filters is for each indicator form to be live even if you are using Filament's [filter deferring](https://filamentphp.com/docs/3.x/tables/filters/getting-started#deferring-filters). Since each indicator is a subset of all the filters, deferring a single filter doesn't seem necessary.

However, if there is sufficient demand/need for it, I will look into bringing deferring to Quick Filters in the future. If implemented, each indicator dropdown would have it's own "Apply" button. Please contact me if this is a feature you need.

### Disabling Quick Filters

You may disable Quick Filters per table by overriding the `quickFiltersAreEnabled()` method on your List page:

```php theme={null}
class ListOrders extends ListRecords
{
    use AdvancedTables; 

    public static function quickFiltersAreEnabled(): bool
    {
        return false;
    }
    ...
```

## Current Limitations and Unknowns

While Quick Filters should work for the majority of implementations, there are currently a few limitations and unknowns:

1. Custom filters may not be fully supported, but the goal is to support any implementation with Filament's filters. If something is not working as expected please contact me.
2. Third-party filter plugins have not been tested. If a filter plugin is not working, please contact me. Please note, that full support may require the plugin developer to update their filter.
3. Filament's Query Builder Filter is not currently supported.