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
cardcomponent - For a link sidebar - use the
linklistcomponent - 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
emptyslot 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
| Slot | Required | Description |
|---|---|---|
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. |
items | Yes | Pre-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
| Prop | Type | Default | Description |
|---|---|---|---|
title_tag | Enum: strong, h2, h3, h4 | h3 | Tag used for the title element. |
is_loading | boolean | - | Sets aria-busy="true" on the items region. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.subtle | Emphasis | - | Lower emphasis; a muted, quieter weight. |
.neutral | Emphasis | Yes | Default emphasis; the standard weight at balanced contrast. |
.accent | Emphasis | - | Higher emphasis; a stronger, louder weight. |
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.fluid | Layout | - | Full-width, no max-width. |
.contained | Layout | Yes | Constrained 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.
Related
- card - typical item inside a collection grid
- pagination - pagination control passed into the
paginationslot - filter - filter form passed into the
filtersslot - select - sort control the consumer renders into the
sortslot, shown in the results bar beside the count