Livewire Filters

Filters now show the URL's selection on the first render, plus three static caching fixes.

Changed

• Filters and lf-sort read the URL's filter params when they mount, in both the custom query string and the Livewire query string modes. Before, every control rendered empty and filled in after a second Livewire request, and {{ nocache }} regions returned empty controls. In a browser test of the demo site at 150 ms network latency, filter controls showed the URL's selection after about 365 ms instead of about 1,075 ms (#112).
• The lf-checkbox, lf-radio, lf-select, lf-toggle, lf-text, lf-date, lf-range and lf-sort views show the selection in the server HTML (checked, selected, value). The Alpine-driven lf-checkbox-advanced, lf-select-advanced and lf-dual-range views show it as soon as Livewire starts (#112).
• The collection sends preset-params only when a filter param doesn't come from the URL, such as a preset on the livewire-collection tag. It then carries every filter param, URL ones included, and only filter keys (field:condition style) and sort (#112).

Fixed

• Under full-measure static caching, {{ livewire-filters:head }} waits for DOMContentLoaded before starting Livewire, so alpine:init listeners placed after {{ livewire:scripts }}, such as ones that register Alpine.store, run in time. Before, expressions using them sometimes threw errors (#116).
• With custom_query_string and full-measure static caching, filter changes no longer sometimes leave the browser URL unchanged, which lost the filters or page on reload (#117).
• With custom_query_string and {{ nocache }} regions on full measure, a paginated URL such as /cars/search/brand/audi?page=2 opens on that page instead of page 1 (#118).

Upgrading

Sites that use the bundled views need no changes. Check these if they apply:

• Custom filter components that relied on preset-params for a URL param no longer receive it. Read CustomQueryString::urlParams() at mount; filters that use the IsLivewireFilter trait and define setPresetValues() get this automatically.
• Custom preset-params listeners that read a key without a colon, such as limit, no longer receive it.
• Published filter views keep working but only show the selection once Livewire starts. Copy the new @checked, @selected and value attributes from the bundled views to get it in the server HTML.
• Published livewire/utility/url-handler.blade.php: re-publish it or merge in the new script to get the URL fix.

Full changelog: https://github.com/reachweb/statamic-livewire-filters/compare/v4.6.2...v4.6.3

A performance release: faster faceted counts, range bounds and filter options on the Stache, smaller Livewire responses and fewer Livewire requests. Results, counts and bounds are the same as before.

Requirements

• Statamic 5 sites need 5.29 or later. On an older 5.x, composer update keeps you on 4.6.1, so nothing breaks; update Statamic to get this release. Statamic 6 is unchanged.

Changed

• Faceted counts and dynamic range bounds find the matching entries once per filter state per request and read each field straight from the Stache index, instead of running one sorted query per filter. On a 5,000-entry collection with 8 filters, the counts request after page load drops from about 1 s to 300 ms, and requests after filter changes get about 25% faster. The Eloquent driver is unchanged (#99).
• Term and entry option labels are read from the Stache indexes instead of loading every term and entry, which makes mounting a filter over a large taxonomy or collection several times faster. Filter option lists are no longer written to the cache store on every page view, so lw_computed cache files stop piling up (#100).
• With enable_filter_values_count off, filter snapshots no longer carry a placeholder counts array, which made up nearly half of a large filter's request (#100).
• Filters no longer send HTML back for renders the browser discards: views with a bare wire:ignore root (the advanced checkbox and select views), params-updated events when counts or bounds are off or unchanged, and clear-option events for another field's tag (#101).
• Fewer Livewire requests: the bundled checkbox view sends filter-updated from the browser in the same request as its own update, the bundled lf-count view updates from the entries-updated browser event, the collection skips tags-updated on page load when there is no tag to show, and the collection's Clear all only asks a filter to relay when it manages a kept param or its selection changed while the clear was on its way (#111, #102).
• entries-updated now also carries entriesLabel, the translated count text. clear-all-filters from the collection now carries two arguments: the condition keys it kept and the params it removed (#111, #102).
• validate_filter_values still rejects invalid checkbox values and shows the error, but no longer stops the bundled checkbox view from applying them. allowed_filters and blocked_query_params still control which params the collection accepts (#111).

In a browser test of the demo site covering every bundled filter and view, the same filtering sessions made 8–26% fewer Livewire requests, and with counts or bounds on received 16–27% less response data, on Livewire 3 and 4 and with every static caching strategy.

Fixed

• Under full-measure static caching, {{ livewire-filters:head }} now starts Livewire even when its script runs after Statamic has replaced the CSRF token, for example when it sits after a stylesheet. Before, filters could stay unresponsive on slow networks. Placing the tag before your stylesheets is now recommended (#102).
• A selection made while Clear all was on its way no longer stays applied after the filter resets (#102, #115).

Upgrading

Sites that use the bundled views, or published copies of them, need no changes. Check these if they apply:

• Custom views that read $statamic_field['counts'] (none of the bundled views ever did): with counts off the key is no longer set. Use $this->counts[$value].
• Subclasses of LfCheckboxFilter that define payload(), updatedSelected() or dispatchFilterUpdated() keep the server relay and work as before, without the saved request.
• Published lf-checkbox.blade.php or ui/count.blade.php keep working through the server. Re-publish lf-checkbox.blade.php to get the saved request; delete a published count.blade.php to get it for the count.
• Custom clear-all-filters listeners that declare parameters now receive the kept keys and the removed params, in that order.

The full list is in the CHANGELOG.

Full changelog: https://github.com/reachweb/statamic-livewire-filters/compare/v4.6.1...v4.6.2

Security

• Faceted counts now only use the encrypted filter state that the collection sends, the same one dynamic range bounds use. A crafted params-updated event could previously put query controls into the count query and reveal whether matching draft, future or other-site entries exist (#87).
• The view property of every filter component is now #[Locked]. Before, only LfDualRangeFilter locked it. Setting view on the tag still works (#95).

Changed

• params-updated always carries its second argument, the encrypted query, when enable_filter_values_count or enable_dynamic_range_bounds is on. Custom code that dispatches params-updated to refresh counts must pass it; events with only plain params no longer update counts (#87).
• The bundled filters now extend a new abstract LivewireFilter class that implements a FilterContract interface. The IsLivewireFilter trait is unchanged for custom filters. Subclasses of a bundled filter that define payload(), emptyValue(), applyPreset() or dispatchFilterUpdated() must match the new signatures, and LfTextFilter/LfDateFilter subclasses that define rules() are now validated when validate_filter_values is on (#95).
• LfRangeFilter sends its own modifier in filter-updated instead of null; existing filters behave the same (#95).

Fixed

• A dual-range filter on a date field no longer crashes with A non-numeric value encountered when the slider moves after a URL or tag preset. Removing a preset date tag now clears it (#97).
• Removing a dual-range tag now resets only the bound that tag names, also when both bounds hold the same value. Custom tag views should pass the tag's condition as the third argument of removeOption (#97).
• With enable_dynamic_range_bounds on, Clear all keeps range sliders within the full-collection bounds instead of the tag's absolute min/max (#94).
• Pretty URLs with several query_scope aliases now apply every scope, not only the last one (#93).
• condition="taxonomy" on a field whose handle isn't a taxonomy handle now throws TaxonomyFieldHandleMismatchException at mount, naming the field to rename, instead of crashing with Call to a member function collections() on null (#88).
• Faceted counts no longer crash on fields that hold nested arrays or objects, such as Carbon dates on the Stache driver (#90).
• On multi-collection tags, faceted counts and range bounds now query the same collections: those whose blueprint contains the field (#89).
• Terms fields spanning several taxonomies key their options by taxonomy::slug, so counts match and same-slug terms no longer overwrite each other (#91).
• Localized term routes now filter by the default-locale term slug (#92).
• Date dual-range filters clear their params even before their first dispatch, and tags no longer disappear for fields whose handle starts with a scope name (#96).

Upgrading

• If you published tags.blade.php, pass $tag['condition'] as the third argument of removeOption.

Full changelog: https://github.com/reachweb/statamic-livewire-filters/compare/v4.6.0...v4.6.1

Security: query parameter hardening

Livewire keeps the active filter state in a public property, so a crafted request could inject Statamic query controls such as status, from, site or limit into it and change which entries are returned instead of filtering them. This release blocks that by default, with no configuration needed.

New

• blocked_query_params config option: a populated blocklist of Statamic query-control keys (status, from, site, limit, paginate, since/until, filter and more), stripped from client-supplied filter state before the query runs. Matching is on the segment before the first colon, so status also blocks status:is. Parameters set on the {{ livewire-collection }} tag or by an init hook are always kept, and allowed_filters can let a specific key back through.
• Dynamic range bounds (opt-in): set enable_dynamic_range_bounds to true and range and dual range sliders narrow to the values that still match the other active filters. A visitor's own selection is never moved, and a slider with no room left is disabled. Custom views can listen for the new range-bounds-updated event.

Changed

• Removing a filter from the tags, or clicking "Clear all", now updates the collection in one Livewire round trip instead of two (#85).
• Filter identity properties (field, condition, modifier, collection, blueprint, statamic_field) are now #[Locked].
• setParameters() on LivewireCollection is now protected, so the client can no longer call it.
• Filter state keys starting with : are rejected, since Statamic would evaluate them as Antlers expressions.
• URL filter state is sanitized on page load, and tag-only parameters (from, view, paginate, allowed_filters and the collection aliases) are never read from the URL.
• Faceted counts use the same filtered state as the entries query, and the count listener does nothing when enable_filter_values_count is off.
• An event that changes nothing no longer re-renders the collection. If you dispatched filter-updated to force a refresh, call Livewire's $refresh on the collection instead.
• The params-updated event carries the hardened parameters and a second argument (the encrypted bounds query). One-argument listeners keep working.

Fixed

• Moving a range slider back to its default now clears the filter.
• Toggle filters with a numeric or boolean preset_value now show as on when restored from the URL.
• Removing a tag for a parameter without a filter component on the page now works.
• allowed_filters now checks each active query scope on its own, so two active scope filters no longer drop both scopes.

Upgrading

• If you cache your config, run php artisan config:clear or php artisan config:cache after updating. Otherwise the new key stays unset and nothing is blocked.
• If you use static caching, clear it after updating (php please static:clear). Pages cached under 4.5.1 would otherwise drop tag control params like limit or site on the first filter change.
• If a filter targets a field named like a control key (for example status:is), remove that key from blocked_query_params or allow the param with allowed_filters.
• If visitors change limit or another control key through the URL, add it to allowed_filters along with your filter keys.
• "Clear all" now also clears parameters from custom filter components that don't listen for clear-all-filters. Listen for it if the component's own controls should reset.
• If you override filterUpdated(), clearFilter() or clearFilters() in a subclass, add the new optional $boundsSelection = null parameter.
• If you published lf-range.blade.php or lf-dual-range.blade.php and enable dynamic bounds, merge in the range-bounds-updated listener or re-publish the views.

Full details in CHANGELOG.md.

📖 Full guide: https://livewirefilters.com/usage/livewire-collection-tag#securing-parameters

• Fix browser-history behavior when using the addon's custom query string mode

New

• Infinite scroll / "Load more" pagination — add infinite_scroll="true" to the {{ livewire-collection }} tag to enable incremental loading, then render the trigger with the new {{ livewire-filters:load_more }} tag. Use auto="true" for true infinite scroll or omit it for a manual "Load more" button; either way it degrades to a real button without JavaScript. Each load grows the page by the initial paginate value and resets on filter/sort change.

You might need to update your template overrides to use this feature.

Thanks to @mikemartin for kickstarting this feature!

Fixed

• Duplicate browser history entries when paginating in custom query string mode, plus more reliable browser Back button behaviour.
• Static caching on multisite installs: correct site resolution and subdirectory handling.

Improved Static Caching Support

Improves Livewire Filters' support for statically cached pages (full and half measure).

New

• {{ livewire-filters:head }} tag: add it to your layout before {{ livewire:scripts }} to prevent 419 "Page Expired" errors on the first filter interaction under full-measure caching. Outputs nothing when caching is off.
• Better {{ nocache }} handling across all URL modes. Filter state is rehydrated on/!/nocache requests, so filters resolve correctly on a shared cache shell in both the Livewire and custom query string modes (no more stale or "poisoned" filtered pages).

Changed

• Query string modes are now mutually exclusive: when enable_query_string (Livewire) is on, custom_query_string is ignored.

Fixed

• Taxonomy terms with numeric slugs are no longer dropped from filter options and counts.

Please read the full guide to make sure everything is setup correctly for your setup: https://livewirefilters.com/advanced/static-caching

• Fix counts for custom options array.

• Preserve existing (non-filter) query parameters when rewriting custom filter URLs (should fix #69)
• Avoid pushing browser history when the computed URL is unchanged.

• Laravel 13 support

Performance

• Shared count queries — filters with the same base parameters share a single query instead of each running their own.
• Eloquent optimization — on sites using the Eloquent driver, counts pull only the needed field values directly from the database instead of hydrating full entry objects.
• Request-level caching — taxonomy terms, collection entries, dictionary options, and blueprint lookups are cached within the request so duplicate lookups are avoided.

Bug Fixes

• Custom query string URL matching — /myfilters/ no longer incorrectly matches a filters prefix. Matching is now segment-exact.
• Query scope count parameters — fixed incorrect count results when using scoped filters.
• Livewire request detection — now uses the X-Livewire header instead of checking for the livewire/update path, fixing issues with custom Livewire endpoints.
• Multisite path handling — correctly resolves the current page path from the Referer header during Livewire requests.

View Template Changes Only relevant if you've published views with php artisan vendor:publish

There are two changes in lf-checkbox-advanced.blade.php & lf-select-advanced.blade.php :

The Alpine counts property is now initialized with PHP rendered data (keys with null values) instead of an empty object, so Alpine knows which filter options exist from the start: Change: counts: {}, To: counts: @js($this->counts),

The visibility check has been simplified since the keys are now always present: You can change: x-show="counts && counts[value] !== undefined" To: x-show="counts[value] != null"

• Fix: Using sort on a taxonomy filter in a multisite setup displayed terms in mixed/incorrect languages instead of the current site's locale.

• Laravel Boost guidelines.

• Statamic 6 support
• Livewire 4 support
• Fix pagination ?page query string when using custom query sting.

• Fix: Correctly decode URL encoded values

• Fixed: Lazyload placeholder view was always the default (the parameter didn't get through).

• Fixed: Pagination was not reset when the user was using the "Clear filter" button or when removing an option using LfTags.

• Significantly improve the performance of filter option counts.

• Added support for the dictionary field. You can now use the built-in or any custom Dictionaries as a filter.
• Fixed ordering for the entries fieldtype.

• FIX Display the key of a select field when the label is not set.

✨ What's New

• Upgraded to Tailwind v4 This makes customizing the theme, especially for minor color changes, much easier. If you're updating from a v2.x version, please check the installation guide for a required configuration change.

• New Advanced Filters with Alpine.js We've added new "advanced" select and checkbox filters! They are ideal for horizontal layouts, offer consistent styling across different platforms, and can be made searchable. See them in action on the horizontal demo page.

• New Toggle Filter The new Toggle Filter allows you to create filters with preset values that your users can simply turn on or off.

🚀 Improvements & Fixes

• Added a placeholder property to all applicable filters.
• Upgraded the core dependency to marcorieser/statamic-livewire v5.0.0.
• Made several accessibility improvements.
• Fixed various minor bugs.

Added support for entries field.

You can add use an entries relationship field as a filter. The published entries from all associated collections will appear as options.

When using multi-site and a Statamic entries field to filter your entries, Livewire Filters defaults to using each entry’s origin ID. This aligns with Statamic’s behavior, where the origin acts as the source of truth unless the field has been localized. We believe this is the most common use case, as it preserves relationships while allowing the associated entry to be translated.

If you are localizing the entries field itself and want to change this behavior, set the use_origin_id_for_entries_field option to false in the config file. This will make Livewire Filters use the entry ID from the current site for filtering instead.

Changes

• Added a scrollTo property to LivewireCollection to disable or control the target of the scroll after using the paginator. (#41)
• Added a placeholder property to LfTextFilter that allows you to set a placeholder for the input element. (#42 )
• Fixed an issue where the taxonomy terms would appear in the wrong language when using multi site.

Upgrade Notes

• The templates for the pagination (ui/pagination.blade.php) and the LfTextFilter (filters/lf-text-filter.blade.php) need to be upgraded to support the above features. If you have published them, check the original files to copy over the changes.

• Laravel 12 support

New features

• Lazy Loading: The LivewireCollection component now supports lazy loading. Read about it in the docs as well as in Livewire's docs.
• LfCount component and count and active variables in the entries-updates event. Read more here. Thanks to @pixelastronauts for this feature.
• Added a method to allow clearing all filters at once and added a "Clear all" button in LfTags. Again, more info can be found in the docs.

Fixes

• Fixed multi-site queries by using the RestoreCurrentSite trait from the statamic-livewire package. Thanks to @taylanunutmaz and @Biostate for bringing this to my attention.
• Fixed an issue with LfTags when mutliple query scopes were used.
• Fixed an error that caused LivewireCollection to render twice when values were preset.
• Added a command to publish the language file.

Other

• New Tips and Performance page in the docs that will contain some tips and best practices.
• Changed the statamic-livewire package installed to marcorieser/statamic-livewire as @marcorieser is the new maintainer.

Fixed a few issues regarding query scopes:

• You can now apply more than one query scope at a time. (before the key would have been overridden)
• You can preset a query scope in the LivewireCollection tag and another one in the URL and they will both be correctly preset.
• The Multiselect can now apply for more than one field (previously it only applied randomly for the first).
• The Resrv query scope is now recognized so that it doesn't try to implode the search array.

If you are not using query scopes or Resrv you can safely skip this release.

• Fixed an issue that was caused by the LivewireCollection component responding too slowly when adding filter params.
• Removed the command property from the filters-updated event and cleaned up the code.
• Fixed removing a filter from the LfTags component when the selected value was an array.

New filter: Dual Range Filter

A brand new custom build Livewire component that uses a slider to let the user filter entries that fall into the specified values range. More information and documentation: https://livewirefilters.com/docs/v1/dual-range-filter

• Fix: The LfRangeFilter was causing double rendering of the LivewireCollection component (#20). This is now fixed and the default property is deprecated. (you can set a default value in the LivewireCollection component itself)

New feature: Custom URL Query String

Statamic Livewire Filters can now generate easy to read, SEO-friendly URLs when the user is using the filtering system.

Read the docs: https://livewirefilters.com/docs/v1/url-query-string#content-using-livewires-url-query-parameters Live demo: https://livewirefilters.com/docs/v1/advanced-example/search/brand/citroen,toyota,vw/categories/crossover-suv/transmission/automaticTransmission

• New Feature: Filter options are now sortable. For more information, see the documentation on sorting filter values.
• Documentation: Added a "Common Issues" page to the docs cover common misconfigurations and other issues.

• Fixed getting the correct options for array based fields since Statamic changed the way they are saved in https://github.com/statamic/cms/pull/10467

• Statamic v5 and Laravel v11 support.

• FIX Added some filtering to the LfTags Livewire component so that it ignores parameters that don't contain the : character and are probably not filter conditions.
• FIX The LfTags component now ignores completely fields not in the fields property. This approach is better as before it would display filtering you might have been doing using the tag but do not offer to the user to adjust.

IMPORTANT The URL for the documentation and examples is now https://livewirefilters.com

• NEW LfTags component that allows you to display a "tags" or "pills" section of available tags. Read more.
• NEW Added a {{ pagination_total }} variable that allows you to show the total number of entries when using pagination. Read more.
• FIX Overriding the filter options by providing an array of 'value' => 'label' arrays is fixed. This feature is still undocumented.

• NEW Add support for Hooks. Statamic v4.50.0 added support for hooks, allowing you to "hook" into the Collection tag to perform an action into the Entries data. This version adds a hook called livewire-fetched-entries for Livewire Filters.

How to use In your AppServiceProvider you can register a hook like so:

#292D3E; --theme-selection-background: #00000080;">
#89DDFF;">\Reach#89DDFF;">\StatamicLivewireFilters#89DDFF;">\Http#89DDFF;">\Livewire#89DDFF;">\LivewireCollection#89DDFF;">::#82AAFF;">hook#89DDFF;">(#89DDFF;">'livewire-fetched-entries#89DDFF;">'#89DDFF;">,
    function #89DDFF;">($entries#89DDFF;">, #89DDFF;">$next#89DDFF;">) #89DDFF;">{
#89DDFF;">        #676E95;">// The parameters of the component if you need them
        #89DDFF;">$params #89DDFF;">= #89DDFF;">$this->params#89DDFF;">;
 
        #89DDFF;">$entries#89DDFF;">->#82AAFF;">each#89DDFF;">(function #89DDFF;">($entry#89DDFF;">) #89DDFF;">{
#89DDFF;">             #676E95;">// Do something with the data here
        #89DDFF;">});
 
        #89DDFF;">return #89DDFF;">$next#89DDFF;">($entries#89DDFF;">);
    #89DDFF;">}
#89DDFF;">);

For example you might call an API and attach extra data to the entries, or you might want to display some data only if a specific filter is active. The sky is the limit!

You need to be at least on Statamic v.4.50.0 to use this release, if you cannot upgrade at the moment you can stay at v1.6.0 of this addon.

• NEW Entry counts for filter options. Livewire Filters can now calculate and display counts for each option in checkboxes, radio, and select fields next to their labels. This feature is resource-intensive, as it performs a query for each filter option on the page and repeats these queries after each user action to update the counts. Therefore, it should be used cautiously, especially with large data sets. By default, this feature is disabled in the config file.

Please add this to your config file if you are upgrading from a previous version and wish to enable this feature.

#292D3E; --theme-selection-background: #00000080;">
#676E95;">// The addon will calculate the number of entries for each filter value (can be slow for a large number of entries)
#89DDFF;">'enable_filter_values_count#89DDFF;">' #89DDFF;">=> #89DDFF;">true,

• NEW allowed_filters parameter. You can now specify which filters are permissible, you can set a parameter that defines the allowed conditions. This is achieved by passing a pipe-separated list of permissible filters. More info: https://slf.reach.gr/docs/v1/livewire-collection-tag#content-parameters

• REMOVED The only_allow_active_filters setting has been removed. Someone could just sniff the payload between the main LivewireCollection component and the filters and send the appropriate filiter-mounted event before sending the filter it wasn't offering that much protection anyway. If you were using it you need to migrate to the allowed_filters parameter above.

Please copy over your config again if you are upgrading from a previous version

This release adds new config options for the features that were added:

#292D3E; --theme-selection-background: #00000080;">
#676E95;">// If enabled the addon will preset the term parameters in any taxonomy term routes
#89DDFF;">'enable_term_routes#89DDFF;">' #89DDFF;">=> #89DDFF;">false,

• NEW The tag now automatically applies the filter for a Statamic taxonomy term route
• FIX Filters are pushed in the filters collection on every component boot, so lets clean up.

• Revert the "fix" for the any modifier as it doesn't work with only_allow_active_filters.

• Added the step option to the LfRangeFilter
• Fixed the any modifier usage in order to better adhere with Statamic's convention.

Please copy over your config again if you are upgrading from a previous version:

#292D3E; --theme-selection-background: #00000080;">
php artisan vendor:publish --tag statamic-livewire-filters-config

This release adds new config options for the features that were added previously:

• only_allow_active_filters: when enabled, the addon only allows filtering by filters and conditions that are loaded at the page. This improves data security as without it a user could perform any Statamic condition, whether you wanted to allow it or not. Defaults to true. You might want to disable it if you are generating your filters dynamically or if you are lazy loading the filters and the active filters do not get registered.

• validate_filter_values: when using fields that have predefined options the addon would validate that the value the user wants to filter by, actually exists in the options array. Defaults to true.

• NEW The LivewireCollection component now registers the fields and conditions of the filters in the page and only allows filtering by them. This was added to prevent passing conditions that would reveal information you might not want, like Entries that are unpublished.
• FIX The query_scope preset values weren't displayed in the filters.

• Select and Checkboxes filters now validate that the option is in the available options array or fail.
• Testing setup on GitHub.

• Added the entries-updated event.
• Fixed the issue with Flatpickr CSS not being included.
• Removed redundant code from LfSelectFilter
• Added docs link: https://slf.reach.gr/

• Pagination should reset on filter or sort change

• Use @tailwindcss/forms with class strategy to prevent resetting other forms on the page
• Add wire:key to the default collection Antlers template

First release