Skip to main content

Collection

Content listing section with title, filters, items, results count region, sort control, pagination, and empty state. Collections are slot-driven - the consumer pre-renders filters, items, and pagination and passes them in as slot content. Semetrika does not orchestrate state; it provides the layout, chrome, and accessibility glue. Vertical spacing and background panels are not collection props; apply them via utility classes on the root (e.g. classes: ['space-above-md', 'space-below-md']) or wrap the collection in a <section class="subtle"> to give it a panel surface.

Usage​

When to use

  • Any content listing that needs a title, filters, results, and pagination - news listings, resource libraries, search results, product catalogs
  • When the consumer already has filter / pagination state handled server-side or by a framework and just needs a consistent layout shell
  • Sections of a page that wrap a grid of cards in filter and pagination chrome

When not to use

  • For a single card - use the card component
  • For a link sidebar - use the linklist component
  • For a full page template - use an Example page, not a collection
  • When the section has no items, no filters, and no pagination - the collection chrome adds no value

Do

  • Provide a meaningful <label> for the sort control, even if it is visually hidden
  • Use the empty slot to explain what the user can do when no items match
  • Keep the filter toggle button text descriptive on mobile (e.g. "Show filters")

Don't

  • Expect Semetrika to filter or paginate the items - the consumer renders the state
  • Nest collections inside collections
  • Use collection as a page-level template

API​

Slots​

SlotRequiredDescription
title-Section heading text.
content-Optional description text under the title.
filters-Pre-rendered filter form.
results_count-Results count text rendered inside an aria-live="polite" region.
sort-Sort control (typically a select) rendered in the results bar beside the results count.
itemsYesPre-rendered items content as an HTML string (typically a grid of cards). Pass a real array via a separate prop if you need item-level iteration.
empty-Empty-state message rendered when items is empty.
pagination-Pre-rendered pagination control.
footer-Footer content rendered below pagination.

Props​

PropTypeDefaultDescription
title_tagEnum: strong, h2, h3, h4h3Tag used for the title element.
is_loadingboolean-Sets aria-busy="true" on the items region.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.fluidLayout-Full-width, no max-width.
.containedLayoutYesConstrained to a max-width.

Examples​

Empty state​

Empty state slot shown when no items match.

Loading state​

Loading state with aria-busy.

With cards​

Six results rendered as cards, the item type for a listing that leads with imagery.

With snippets​

The same six results rendered as snippets, the item type for a text-led listing such as search results.

Accessibility​

  • WCAG 2.2 AA
  • Section heading matches the document outline.
  • Results count is an aria-live="polite" region so filter updates are announced without stealing focus.
  • Loading state sets aria-busy="true" on the items region.
  • card - typical item inside a collection grid
  • pagination - pagination control passed into the pagination slot
  • filter - filter form passed into the filters slot
  • select - sort control the consumer renders into the sort slot, shown in the results bar beside the count