Livewire Collection tag

General

The {{ livewire-collection }} tag is the cornerstone of this addon. It is responsible for loading the main Livewire component, LivewireCollection, and can handle almost all the parameters and syntax of the original {{ collection }} tag.

For instance, if you have a collection tag like this:

{{ collection:cars paginate="10" sort="title:asc" }}
    {{# Your template here #}}
{{ /collection:cars }}

You can replace it like so:

{{ livewire-collection:cars paginate="10" sort="title:asc" }}

Why a tag and not a Livewire component?

Using a Statamic tag to load the Livewire component might seem complex, but it's the most effective way to ensure compatibility with all parameters supported by Statamic's collection tag, both now and in future updates.

Preset filters

This tag can manage almost all collection parameters, passing them to the Livewire component. When using conditions, they are parsed, and the collection is filtered accordingly. If an active filter component for the condition exists, the filter will automatically populate with the correct values. Which means you can do stuff like and expect them to just work:

{{ livewire-collection:cars taxonomy:car_brand:any="toyota" max_passengers:gte="4" }}

To see preset conditions examples in action, visit the relevant section.

Take care with the any modifier

In Statamic, the any modifier is implied when setting taxonomy conditions. Livewire Filters adhere to this convention: if no modifier is set, any is used by default. However, if you want to preset taxonomy values using the any modifier, ensure that it's added to any preset conditions, like the example above. Otherwise, the filter won't automatically populate the values.

Other parameters

The {{ livewire-collection }} also accepts the following parameters:

• view: Select a different view (template) for the entries, enabling the use of varied templates for different collections. For example, view="cars" will search for the template at resources/views/vendor/statamic-livewire-filters/livewire/cars.antlers.html.
• paginate: While this is a parameter of the original collection tag, here it replaces the pagination with a pre-built Livewire-compatible one. Use the {{ links }} variable in your template for pagination (read more below).
• lazy: Set this to true to enable lazy loading (also read more below).
• infinite_scroll: Enable incremental "load more" pagination instead of numbered links, rendered with the {{ livewire-filters:load_more }} tag (read more below). Requires paginate to be set.

Limiting Allowed Filters

Given that this addon leverages Laravel Livewire, it's important to note that all server requests can potentially be modified by a malicious user. This could lead to unintended conditions being applied, such as listing draft entries. While this may not be a significant concern since the data being filtered is public, you might still wish to restrict the filters users can apply for enhanced security.

To specify which filters are permissible, you can set the allowed_filters parameter that defines the allowed conditions. This is achieved by passing a pipe-separated list of permissible filters. For example:

{{ livewire-collection:cars paginate="6" allowed_filters="taxonomy:car_brand:any|transmission:is" }}

When using with query_scopes you need to allow both parameters:

{{ livewire-collection:cars paginate="8" allowed_filters="taxonomy:car_brand:any|query_scope:multiselect|multiselect:special_categories" }}

Pagination

Pagination is seamlessly managed by the LivewireCollection component. Simply include the paginate property in the tag to activate it. Within your template, use the {{ links }} tag to generate a TailwindCSS-styled pagination control.

If you prefer to customize the pagination appearance, you can modify the default pagination template located at vendor/statamic-livewire-filters/livewire/ui/pagination.blade.php.

For situations where you need to display the total number of entries (e.g., "Showing 5 of 60 results"), remember that using {{ entries | count }} will only count the entries on the current page. To display the total number of entries across all pages, use the {{ pagination_total }} variable anywhere within your template.

Controlling Pagination Scroll Behavior

By default, pagination scrolls back to the top of the page when changing pages. You can disable this behavior by setting the scrollTo property on LivewireCollection to false.

Alternatively, you can specify a custom scroll target by setting scrollTo to a relevant class or ID. For example scrollTo="#content".

Infinite scroll (load more)

Instead of numbered page links, a paginated collection can pull more entries into the same page, either when the visitor clicks a button, or automatically as they scroll (true infinite scroll).

Enable it with infinite_scroll="true":

{{ livewire-collection:cars paginate="12" infinite_scroll="true" }}

Then render the trigger in your view with the {{ livewire-filters:load_more }} tag — think of it as the "load more" counterpart to {{ links }}:

{{ livewire-filters:load_more }}              {{# manual "Load more" button #}}
{{ livewire-filters:load_more auto="true" }}  {{# auto-loads on scroll #}}

• Without auto, it renders a "Load more" button the visitor clicks.
• With auto="true", it additionally wires up Alpine's x-intersect so the next page loads automatically as the trigger scrolls into view.

Each load grows the page size by the initial paginate value (so the example above loads 12 more entries at a time), and the size resets automatically whenever a filter or sort changes. The tag hides itself once there are no more pages, so you don't need to wrap it in a condition.

Requires paginate

Infinite scroll builds on pagination, so paginate must be set. If it's missing (or 0), infinite_scroll is ignored and the collection renders normally.

The default view already includes the tag, so the basic setup works out of the box. You only have to add it yourself when using a custom view.

Customizing the trigger

The {{ livewire-filters:load_more }} tag accepts:

Parameter	Description
auto	Set to true to auto-load on scroll. Defaults to a click-to-load button.
text	Override the button label. Defaults to the translatable statamic-livewire-filters::ui.load_more string.
class	CSS classes for the <button> element.

text and class are output as-is, like any Antlers variable. If you bind either to untrusted input (e.g. a request value), sanitize it at the call site — text="{{ value | sanitize }}".

For full control over the markup, publish and edit the template at vendor/statamic-livewire-filters/livewire/ui/load-more.antlers.html.

State lives in the component, not the URL

The "loaded more" state is kept in the Livewire component rather than the URL. A full page reload therefore resets the list back to the first page — so infinite scroll is best suited to discovery-style listings rather than deep-linkable, shareable result sets.

Lazy loading

You can lazy load the LivewireCollection component by adding the lazy="true" parameter.

By default, the component uses the resources/views/livewire/ui/lazyload-placeholder.blade.php file as a skeleton. Feel free to modify this file to suit your needs.

If you need different skeleton templates for different collections, you can set the lazy-placeholder parameter in your component to specify a custom template.

Passing data to the Livewire template

Since we're using a tag and not a partial your page variables will not be available in the Livewire template. There are times when you might want to pass some one-off parameter to the Livewire view. To do that just pass it using the tag:

{{ livewire-collection:cars view="cars" image_size="large" }}
``

Then in your `cars.antlers.html` file in the Livewire Filters vendor folder you can access the `image_size` variable inside the `params` array:

```antlers
{{ params:image_size }}
``