Download the PHP package shallowred/kirby-collection-manager without Composer

Kirby Collection Manager

AJAX-powered collection listings for Kirby CMS: search, filters, sorting and pagination, rendered server-side and enhanced with htmx. Works without JavaScript, supports several independent collections on the same page, and ships with sensible default snippets you can override.

Installation

Requires PHP 8.1+ and Kirby 4 or 5.

Quick start

The plugin follows Kirby's controller/template split. In a controller (page controller, snippet controller or block controller), hand your collection to CollectionController::handle():

Then render the wrapper snippet in the template:

That's it: search form, filter pills, paginated items — with AJAX swaps when JavaScript is available, plain links and form submits when it is not.

There is also a shorthand page method:

Configuration

All keys are optional; defaults shown below.

Visitor-facing sorting

Offer sort options with the field:direction syntax (direction defaults to sorting.direction). Requested values are validated against this whitelist.

Multi-select filters

Set 'multiple' => true on a taxonomy to let visitors combine values. Options toggle in and out of a comma-separated param (?category=Design,Engineering) and items match when any of their values match.

Several collections on one page

Give each instance its own pagination param — everything else (fragment targeting, URL generation) is scoped automatically:

Custom item template

Point snippets.item to your own snippet; it receives $item (the page), $orderIndex and $config:

Any other snippet (search, filters, pagination, sorting, indicator, wrapper) can be overridden the same way, or globally by creating a snippet with the same name in site/snippets/.

Styling

Three levels of customization, from lightest to fullest. They compose freely.

1. Default stylesheet + CSS variables

Enable the bundled stylesheet (injected once, however many instances):

Or include it manually:

The whole file lives in the collection-manager cascade layer, so any rule in your own stylesheet overrides it — no specificity fights. Theme it by overriding the --cm-* variables:

Dark mode follows prefers-color-scheme automatically, or force it with a .cm-dark class (also honors [data-theme="dark"]).

2. Custom classes (Tailwind / UnoCSS / DaisyUI)

The classes config appends your utility classes to every element the plugin renders — the default BEM classes stay in place, so behavior, tests and the default stylesheet keep working:

Available keys: wrapper, search, searchInput, searchSubmit, searchClear, filters, filterGroup, filterLabel, filter, filterActive, filtersClear, sorting, sortingLabel, sortingSelect, items, item, empty, pagination, paginationItem, paginationIcon, indicator.

3. Custom snippets

For full control over the markup, override any snippet (see below).

How the AJAX layer works

The wrapper snippet loads a bundled htmx (once per page, however many instances there are) and every control targets the instance's content element. The server detects fragment requests through the HX-Target header, so URLs stay clean and shareable — a reload of any URL renders the full page. Fragment responses send Vary: HX-Target for cache correctness. Out-of-range page numbers (e.g. a stale link to page 3 of a filtered list) are clamped to the nearest valid page instead of erroring.

Translations

English, French and German are built in. Override or add languages in your config:

Demo & tests

A demo site lives in demo/ (requires a Kirby core in demo/kirby, not versioned). The Playwright end-to-end suite runs against it:

PHP linting: composer lint.

License

MIT