Data display

Collection toolbar

<forma-collection-toolbar>

A responsive composition for search, filters, sort, saved views, and result counts.

Authoring tag
<forma-collection-toolbar>
Category
Data display
Behavior owner
Application / Limen
Canonical source
patterns/collection-toolbar.html

Purpose

A collection toolbar sits above a list or Data grid and gathers the controls that shape it: a search form, a native details disclosure holding filters, sort and saved-view selects, and a result count in a role="status" element. Forma lays these out in a three-area grid that recomposes on phones, keeping search first and the count visible. All controls are native; running the search, applying filters, sorting, persisting views and updating the count are application behavior (normally Limen).

Use when

  • A collection of records can be searched, filtered, sorted or switched between saved views.
  • The result count must stay visible and be announced when it changes.
  • Secondary controls should collapse on phones without hiding the current filter state.

Avoid when

  • Only a search box is needed: use Search on its own.
  • Filters are numerous or complex enough to need their own surface: open them in a Flyout from the toolbar and summarize them with Active filter summary.
  • The controls act on selected rows (delete, assign): those are bulk actions, not collection shaping; keep them separate.
  • The controls switch between unrelated sections of content: use Tabs.

Behavior to know

  • Desktop grid: search minmax(14rem, 1.6fr), controls minmax(0, 2fr), count auto, aligned to the bottom edge.
  • Filters live in a native details; the panel is positioned over the content on wide screens and flows inline on phones.
  • The filter summary carries the active-filter count as text, so state is visible while the panel is closed.
  • The count uses small monospace text and never wraps.

Basic example

The smallest correct markup: the canonical pattern from patterns/collection-toolbar.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal collection toolbar

Rendered from the canonical pattern file.

Live demo. 1 native action works here and is verified by an outcome test.

Filters 2 active

24 records

HTML · Minimal collection toolbar Raw HTML for HTML · Minimal collection toolbar
<forma-collection-toolbar class="forma-component-tag">
<section class="forma-collection-toolbar" aria-label="Collection controls">
  <form class="forma-search forma-collection-toolbar__search" role="search">
    <label class="forma-search__label" for="collection-search">Search records</label>
    <input id="collection-search" type="search" placeholder="Search">
  </form>
  <div class="forma-collection-toolbar__controls">
    <details class="forma-collection-toolbar__filters">
      <summary>Filters <span class="forma-status-lozenge">2 active</span></summary>
      <div class="forma-collection-toolbar__filter-panel">
        <label>Status <select><option>Any status</option><option>Needs attention</option><option>Complete</option></select></label>
        <label>Owner <select><option>Anyone</option><option>Me</option></select></label>
      </div>
    </details>
    <label class="forma-collection-toolbar__sort">Sort
      <select><option>Most recent</option><option>Oldest</option><option>Name</option></select>
    </label>
    <label class="forma-collection-toolbar__view">Saved view
      <select><option>All records</option><option>Needs my attention</option></select>
    </label>
  </div>
  <p class="forma-collection-toolbar__count" role="status">24 records</p>
</section>
</forma-collection-toolbar>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Search term with active filters

A search term and two applied filters. The filter panel is closed, but its summary text states "2 active", so the state stays visible. On wide screens the panel, when opened, is positioned over the content below the toolbar.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Filters 2 active

3 invoices

HTML · Search term with active filters Raw HTML for HTML · Search term with active filters
<forma-collection-toolbar class="forma-component-tag">
  <section class="forma-collection-toolbar" aria-label="Invoice list controls">
    <form class="forma-search forma-collection-toolbar__search" role="search">
      <label class="forma-search__label" for="collection-toolbar-active-filters-search">Search invoices</label>
      <input id="collection-toolbar-active-filters-search" name="q" type="search" value="acme">
    </form>
    <div class="forma-collection-toolbar__controls">
      <details class="forma-collection-toolbar__filters">
        <summary>Filters <span class="forma-status-lozenge">2 active</span></summary>
        <div class="forma-collection-toolbar__filter-panel">
          <label>Status <select name="status"><option>Any status</option><option selected>Overdue</option><option>Paid</option></select></label>
          <label>Owner <select name="owner"><option>Anyone</option><option selected>Me</option></select></label>
          <button type="button">Clear filters</button>
        </div>
      </details>
      <label>Sort <select name="sort"><option>Due date, soonest</option><option>Amount, highest</option></select></label>
    </div>
    <p class="forma-collection-toolbar__count" role="status">3 invoices</p>
  </section>
</forma-collection-toolbar>

Click or tap the code once to select all of it, then copy.

Scenario

Search with no results

A search that matches nothing. The count states 0 results in the status region; the filters summary shows none are active, so the user knows the search term alone caused the empty result.

Live demo. 1 native action works here and is verified by an outcome test.

Filters None active

0 customers

HTML · Search with no results Raw HTML for HTML · Search with no results
<forma-collection-toolbar class="forma-component-tag">
  <section class="forma-collection-toolbar" aria-label="Customer list controls">
    <form class="forma-search forma-collection-toolbar__search" role="search">
      <label class="forma-search__label" for="collection-toolbar-no-results-search">Search customers</label>
      <input id="collection-toolbar-no-results-search" name="q" type="search" value="northwnd">
    </form>
    <div class="forma-collection-toolbar__controls">
      <details class="forma-collection-toolbar__filters">
        <summary>Filters <span class="forma-status-lozenge">None active</span></summary>
        <div class="forma-collection-toolbar__filter-panel">
          <label>Region <select name="region"><option>All regions</option><option>Europe</option><option>North America</option></select></label>
        </div>
      </details>
      <label>Saved view <select name="view"><option>All customers</option><option>Key accounts</option></select></label>
    </div>
    <p class="forma-collection-toolbar__count" role="status">0 customers</p>
  </section>
</forma-collection-toolbar>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Mobile collection toolbar

The full toolbar at phone width. Search spans the row, the controls wrap below it, and the filter panel opens inline instead of floating over the list.

Live demo. 1 native action works here and is verified by an outcome test.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • At 40rem (640px) and below the grid becomes 1fr auto: search and the controls each span the full width, and the count sits beside the remaining space.
  • Each control flexes at 1 1 9rem, so sort and saved view share a row when they fit and wrap one per row at 320px.
  • The filter panel switches from absolute positioning to static, full width, with no shadow, so it pushes the list down instead of covering it.
  • The filter summary is at least 2.75rem tall, giving a comfortable touch target; the native selects open the platform picker on phones.
  • Search stays first and the count stays visible at every width; no control is hover-only.
HTML · Mobile collection toolbar Raw HTML for HTML · Mobile collection toolbar
<forma-collection-toolbar class="forma-component-tag">
  <section class="forma-collection-toolbar" aria-label="Ticket list controls">
    <form class="forma-search forma-collection-toolbar__search" role="search">
      <label class="forma-search__label" for="collection-toolbar-mobile-toolbar-search">Search tickets</label>
      <input id="collection-toolbar-mobile-toolbar-search" name="q" type="search" placeholder="Subject or ticket number">
    </form>
    <div class="forma-collection-toolbar__controls">
      <details class="forma-collection-toolbar__filters" open>
        <summary>Filters <span class="forma-status-lozenge">1 active</span></summary>
        <div class="forma-collection-toolbar__filter-panel">
          <label>Status <select name="ticket-status"><option>Any status</option><option selected>Awaiting reply</option></select></label>
        </div>
      </details>
      <label>Sort <select name="ticket-sort"><option>Newest</option><option>Oldest</option></select></label>
      <label>Saved view <select name="ticket-view"><option>My tickets</option><option>Team queue</option></select></label>
    </div>
    <p class="forma-collection-toolbar__count" role="status">12 tickets</p>
  </section>
</forma-collection-toolbar>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Live demo. 1 native action works here and is verified by an outcome test.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-labelsection.forma-collection-toolbarstring—Names the toolbar region after the collection it controls.
roleform / .forma-collection-toolbar__countsearch / status—search makes the form a search landmark; status makes the count a polite live region so result changes are announced.
forlabel.forma-search__labelid of the search input—Associates the visible label with the search input.
typeinputsearch—Native search field with platform clear affordances.
opendetails.forma-collection-toolbar__filtersbooleanabsent (closed)Native disclosure state of the filter panel; the browser toggles it.
nameinput / selectstring—Field names used when the application serializes the query, for example into the URL.
selectedoptionboolean—Initial selected filter, sort or view.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-collection-toolbarBlock class—Root grid of search, controls and count; recomposes at 40rem and below.
.forma-collection-toolbar__controlsElement class—Wrapping flex row of filters, sort and view controls; labels inside get a 9rem minimum width.
.forma-collection-toolbar__countElement class—Result count in small monospace text, no wrapping. Pair with role="status".
.forma-collection-toolbar__filter-panelElement class—The filter fields. Absolutely positioned with a shadow on wide screens; static and full width at 40rem and below.
.forma-collection-toolbar__filtersElement class—The native details holding filters. Its summary is a bordered, 2.75rem-tall button-like row.
.forma-collection-toolbar__searchElement class—The search form area; spans the full row on phones.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through search, the filters summary, each select and any buttons in order.
Enter / Space on summaryOpens or closes the filter panel (native details). Escape does not close it natively.
Enter in searchSubmits the search form; the application runs the query.
Arrow keys / Alt+Down on selectNative select behavior.
Events
EventDescription
submitNative form submission from the search form.
input / changeNative events from the search field and selects; the application re-queries and updates the count.
toggleNative event on the filters details when it opens or closes.

Form behavior

The search is a native form; selects are native form controls that can be submitted or serialized. Forma does not persist queries or views.

States

Collection toolbar states
StateHow it is expressedPresentation
Filters closeddetails without openOnly the summary with its active-count text is visible.
Filters opendetails[open]Filter panel shown over the content (desktop) or inline (phone).
Active filterstext in the summary, for example a Status lozenge reading "2 active"Written by the application; Forma does not count filters.
Result counttext in .forma-collection-toolbar__countAnnounced through role="status" when the application changes it.
Stackedviewport ≤ 40remSearch full width; controls wrap; panel inline.

Accessibility

Forma provides

  • Keeps every control native: search form, labelled selects and a details disclosure with keyboard support from the browser.
  • Keeps search first in DOM and visual order at every width.
  • Gives the filters summary a 2.75rem minimum height.
  • On phones renders the filter panel in flow, so it never covers focused content.

Your application supplies

  • Label the search input and every select; wrap selects in their label or use for/id.
  • Update the count text after every query so role="status" announces it; keep it concise.
  • Keep the active-filter count in the summary text and show the applied filters with Active filter summary.
  • Reflect query state in the URL so views can be shared and restored.
  • If the panel should close on Escape or outside click, implement that in the application.

Responsive behavior

  • Above 40rem: three areas on one row, bottom-aligned.
  • At 40rem and below: search full width, controls full width and wrapping, count beside the leftover space; the filter panel becomes static.
  • Controls flex at 1 1 9rem, so they wrap before becoming unusably narrow.
  • The desktop panel width is min(20rem, calc(100vw - 2rem)), so it never exceeds the viewport.

Motion

  • No animation: the filter panel opens and closes instantly with the native details state; the count updates without transition.

Usage guidance

Do

  • Keep search visible and first; put secondary controls in the controls area.
  • Show the count with its noun ("24 records") so the announcement is meaningful on its own.

Avoid

  • Hiding the active filter count inside the closed panel.
  • Applying filters on hover or requiring drag.
  • Placing bulk actions for selected rows in the collection toolbar.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.