Skip to content

Catalog

A searchable, filterable, sortable collection that keeps its state in the address with no script.

<p>Server-rendered into the page. Every control is a form field or a link, so it works with no script; the behavior swaps the changed regions in place and writes the address.</p>
<div id="catalog-wide" data-catalog-demo></div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/catalog.css";
import { enhance } from "capsomer/behavior/catalog";

enhance();

Usage

<form class="cap-catalog" data-cap="catalog" data-catalog="articles" method="get" action="/library/articles" aria-labelledby="h">
  <div class="cap-field-row">
    <div class="cap-field cap-field-wide">
      <label class="cap-field-label" for="articles-q">Search articles</label>
      <input class="cap-input" id="articles-q" type="search" name="q" />
    </div>
    <div class="cap-field cap-catalog-sort">
      <label class="cap-field-label" for="articles-sort">Sort</label>
      <select class="cap-input" id="articles-sort" name="sort">...</select>
    </div>
    <button type="submit" class="cap-btn cap-catalog-apply" data-variant="primary">Apply</button>
    <a class="cap-btn cap-catalog-tray-open" href="#articles-filters" data-catalog-tray="open">Filters</a>
  </div>
  <div class="cap-catalog-body">
    <div class="cap-catalog-filters" id="articles-filters" role="group" aria-label="Filters" data-catalog-region="filters">
      <fieldset class="cap-field cap-catalog-facet">
        <legend class="cap-field-label">Topic</legend>
        <div class="cap-field-options">
          <label class="cap-check"><input type="checkbox" name="topic" value="pricing" /><span>Pricing</span> <span class="cap-catalog-n">4</span></label>
        </div>
      </fieldset>
    </div>
    <div class="cap-catalog-main">
      <p class="cap-catalog-count" role="status" data-catalog-region="count">3 of 14 articles</p>
      <div data-catalog-region="chips"><ul class="cap-catalog-chips">...</ul></div>
      <div id="articles-results" data-catalog-region="results" aria-busy="false">[the table, or the empty state]</div>
      <div data-catalog-region="pages">[the pagination]</div>
    </div>
  </div>
</form>
import { Catalog } from "capsomer/react/catalog";
import { defineCatalog, parseCatalogParams, queryCatalog } from "capsomer/behavior/catalog";

const def = defineCatalog({ id: "articles", noun: ["article", "articles"], basePath: "/library/articles", itemKey: (p) => p.id, fields: [/* ... */] });
// in the loader: queryCatalog(def, items, parseCatalogParams(def, new URL(request.url).searchParams))
<Catalog definition={def} result={result} labelledBy="page-title" title={(p) => <a className="cap-table-open" href={p.path}>{p.title}</a>} />

Examples

The same catalog in a phone's width: cards, and the filters in a tray over the results

<div id="catalog-narrow" data-catalog-demo style="max-width: 24rem"></div>

API reference

Catalog

PropTypeRequiredDoes
definitionCatalogDefinition<T>Yes
resultCatalogResult<T>YesWhat queryCatalog returned for this request's address.
title(item: T) => ReactNodeYesThe first column's cell: the item's name, usually a link to it.
cellsPartial<Record<string, (item: T) => ReactNode>>A field's cell, when its plain words (the values joined) are not enough.
labelledBystringYesThe page's heading id, which names the results region.
emptyText{ nothingYet?: ReactNode; noMatch?: ReactNode }What to say when the collection itself is empty, and the sentence under "No articles match".
actionsReactNodeBeside the count: downloads, a view switch.

Functions

FunctionSignatureDoes
formHref(form: HTMLFormElement): stringThe form's state as an address: every named control with a value, in the order the form lists them. The server reads it with parseCatalogParams, so a control that is not in the address is at its default.
attachCatalog(form: HTMLFormElement): () => void
enhance(root?: ParentNode): () => voidAttaches to every catalog under root that is not attached yet. Returns a function that detaches them all.

Parts and data attributes

ClassIs
.cap-catalogthe root
.cap-catalog-actionsa part
.cap-catalog-applya part
.cap-catalog-bodya part
.cap-catalog-chipa part
.cap-catalog-chipsa part
.cap-catalog-cleara part
.cap-catalog-counta part
.cap-catalog-faceta part
.cap-catalog-filtersa part
.cap-catalog-groupa part
.cap-catalog-maina part
.cap-catalog-morea part
.cap-catalog-na part
.cap-catalog-sorta part
.cap-catalog-statusa part
.cap-catalog-tray-heada part
.cap-catalog-tray-opena part
.cap-catalog-tray-titlea part
AttributeValues
data-catalog-regionresults
data-enhancedpresent or absent
data-reflowpresent or absent
data-trayopen
StateRead from
:focus-visiblethe platform
:targetthe platform
[aria-busy="true"]an attribute

Accessibility

KeyDoes
TabSearch, sort, Filters (on a phone), each facet's options, then the chips, the results and the pages
Type in searchUpdates the results after a short pause; Enter updates at once
Space on a check or radioChooses it; the results, counts and chips follow
Enter on a chip or Clear allRemoves that filter, or all; focus moves to the count
Escape, with the tray openCloses it and returns focus to "Filters"
  • A labeled form; each facet is a fieldset with a legend; every control has a visible label.
  • The count is a polite live region. The results region is aria-busy while it updates.
  • A removable chip's name says it removes ("Topic: Pricing (remove this filter)").
  • The card layout of the table is the table component's opt-in reflow; it has not yet been checked with a screen reader, so the catalog says so here and an app should check it before relying on it (DEFAULTS.md).
  • Forced colors: chips keep an edge.