@arraypress/filter-toolbar-astro

@arraypress/filter-toolbar-astro

Astro listing toolbar — sort + grid/list view toggle + results count, with a client-side filter / sort / paginate runtime (paged, load-more, or infinite-scroll).

Install

npm install @arraypress/filter-toolbar-astro

Use

---
import { FilterToolbar } from '@arraypress/filter-toolbar-astro';
---
<FilterToolbar resultsCount={products.length} />

<div id="product-grid" class="fb-grid fb-grid--grid">
  {products.map((p) => <ProductCard product={p} />)}
</div>

<script>
  import { initFilterToolbar } from '@arraypress/filter-toolbar-astro/runtime';

  document.addEventListener('astro:page-load', () => {
    initFilterToolbar({
      pageSize: 24,
      currencySymbol: '£',
      paginationMode: 'paged',     // | 'load-more' | 'infinite'
    });
  });
</script>

DOM contract

Cards need data attributes the runtime reads. These are the keys sort/filter logic looks at:

<article
  class="product-card"
  data-category="bundles"
  data-price="49.99"
  data-order="3"
  data-title="Future Bass Vol. 1"
  data-date="2026-04-12"
>
  …
</article>

The toolbar component covers:

• #open-filters — drawer trigger (with #active-filter-count badge)
• #results-count — live count label
• #sort-select — sort dropdown
• #view-grid / #view-list — view toggle

You provide the rest of the markup the runtime expects, with these default ids/classes:

Surface	Default selector	Purpose
Grid container	#product-grid	Wrapper for .product-cards
Category chips	.chip[data-filter="…"]	Buttons that filter by category
Filter drawer	#filter-drawer	Slide-in drawer body
Backdrop	#filter-backdrop	Click-to-close
Drawer close btn	#close-filters
Drawer apply btn	#apply-filters
Drawer clear btn	#clear-filters
Empty state	#empty-state	Shown when no cards match
Price slider	#price-max + #price-max-value
Paged controls	#pagination, #pagination-pages, #page-prev, #page-next
Load-more button	#load-more
Infinite sentinel	#scroll-sentinel

Override any of these via selectors if your markup uses different ids.

Pagination modes

• 'paged' (default) — numbered prev/next + page buttons.
• 'load-more' — "Show more" button reveals the next chunk on click.
• 'infinite' — auto-reveals chunks as #scroll-sentinel enters the viewport (300px rootMargin).

Sort modes

Five built-ins, sorted by reading these card attributes:

Mode	Read from
featured	data-order (asc)
newest	data-date (desc)
price-asc	data-price (asc)
price-desc	data-price (desc)
name	data-title (locale-aware A→Z)

Toolbar props

Prop	Default	Description
resultsCount	''	Initial server-rendered count. Runtime updates it.
sortOptions	DEFAULT_SORT_OPTIONS	Custom sort dropdown options.
showFiltersTrigger	true	Render the Filters button.
filtersLabel	'Filters'
resultsLabel	'results'
showViewToggle	true	Render the grid/list toggle.
sortAriaLabel	'Sort products'	aria-label for the <select>.
class	—	Extra classes on the toolbar root.

Runtime options

initFilterToolbar({
  pageSize: 24,                       // required
  currencySymbol: '£',                // for the price-slider label
  defaultSort: 'featured',
  paginationMode: 'paged',
  loadMoreLabel: 'Show more',
  viewStorageKey: 'ap-view-mode',
  gridClass: 'fb-grid--grid',
  listClass: 'fb-grid--list',
  cardSelector: '.product-card',
  attributeFacets: [ /* optional multi-select facets — see below */ ],
  selectors: { /* override any of the default ids */ },
});

Idempotent — calling twice on the same #product-grid is a no-op. Safe to fire from both DOMContentLoaded and astro:page-load.

Attribute facets

Beyond the single category chip + price slider, you can layer any number of multi-select attribute facets (genre, format, synth, tag, …) via attributeFacets. Each facet reads a delimited token list off a card data attribute and shows a card only if — for every facet with an active selection — the card carries at least one selected token (OR within a facet, AND across facets, AND with category + price).

Card markup — emit space- or comma-separated tokens (use slugs, no internal spaces):

<article class="product-card"
  data-category="pack"
  data-genre="uplifting-trance progressive-trance"
  data-format="presets midi">…</article>

Facet chips — each carries data-value; a data-value="" or data-value="all" chip clears that facet:

<button class="facet-genre" data-value="uplifting-trance" aria-pressed="false">Uplifting Trance</button>
<button class="facet-genre" data-value="progressive-trance" aria-pressed="false">Progressive Trance</button>

initFilterToolbar({
  pageSize: 24,
  attributeFacets: [
    { key: 'genre',  dataKey: 'genre',  chipSelector: '.facet-genre' },
    { key: 'format', dataKey: 'format', chipSelector: '.facet-format', urlParam: true },
  ],
});

Field	Required	Description
key	yes	Stable unique id (also the URL param name when urlParam).
dataKey	yes	Card dataset key — 'genre' reads data-genre.
chipSelector	yes	Selector for the facet's chip buttons (each with data-value).
urlParam	no	Reflect the selection into the URL as ?key=a,b + restore on load.

The runtime toggles .active + aria-pressed on chips, folds active facet values into the #active-filter-count badge, and clears them with the drawer's #clear-filters button. Omitting attributeFacets leaves the existing single-facet behaviour completely unchanged.

Deep-linking

?cat=bundles on the URL auto-clicks the matching chip on first load, so /products?cat=bundles lands users straight on the filtered view.

Styling

The toolbar ships no styles — it emits class hooks only:

.fb-toolbar
.fb-toolbar-filters, .fb-toolbar-filters-label, .fb-toolbar-active-badge
.fb-toolbar-count, .fb-toolbar-count-num, .fb-toolbar-count-label
.fb-toolbar-right
.fb-toolbar-sort, .fb-toolbar-sort-icon, .fb-toolbar-sort-select
.fb-toolbar-view, .fb-toolbar-view-btn (`.active` when picked)

License

MIT