Form inputs

Search

<forma-search>

Search entry, clearing, and result-count feedback with asynchronous behavior owned by the application.

Authoring tag
<forma-search>
Category
Form inputs
Behavior owner
Application / Limen
Canonical source
patterns/search.html

Purpose

Search lets users find records by typing a query. The pattern is a form with role="search" (a search landmark) containing a labelled input type="search", a Clear button and a role="status" line for the result count. Native HTML provides the landmark, the search keyboard on phones, Enter to submit and, in many browsers, Escape to clear. Clearing through the button, debouncing, suggestions, pending state and updating the count are application behavior, normally through Limen.

Use when

  • Users look up records in a collection by keyword.
  • A result count should be announced as results change.
  • The query is the primary way into a list, table or workspace.

Avoid when

Behavior to know

  • The input and Clear button share one row, joined with no gap; at narrow widths the button moves below the input.
  • The status line is a polite live region so count changes are announced without moving focus.
  • Forma renders states; it does not fetch, debounce, rank or clear.

Basic example

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

Canonical

Minimal search

Rendered from the canonical pattern file.

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.

HTML · Minimal search Raw HTML for HTML · Minimal search
<forma-search class="forma-component-tag">
<form class="forma-search" role="search">
  <label class="forma-search__label" for="search-query">Search</label>
  <div class="forma-search__control">
    <input id="search-query" name="q" type="search" placeholder="Search records" autocomplete="off">
    <button type="button" class="forma-search__clear">Clear</button>
  </div>
  <p class="forma-search__status" role="status">24 results</p>
</form>
</forma-search>

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

Examples

Scenario

No matching records

A query that matched nothing. The status line announces zero results and says what to try next; the query stays in the field so it can be corrected.

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.

HTML · No matching records Raw HTML for HTML · No matching records
<forma-search class="forma-component-tag">
  <form class="forma-search" role="search" aria-label="Customers" action="/customers" method="get">
    <label class="forma-search__label" for="search-no-results-query">Search customers</label>
    <div class="forma-search__control">
      <input id="search-no-results-query" name="q" type="search" value="acme holdngs" autocomplete="off">
      <button type="button" class="forma-search__clear">Clear</button>
    </div>
    <p class="forma-search__status" role="status">No customers match "acme holdngs". Check the spelling or search by account number.</p>
  </form>
</forma-search>

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.

Baseline

Mobile · 320px

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

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.

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
roleformsearch—Makes the form a search landmark. Add aria-label when a page has more than one search.
aria-labelformstring—Names the search landmark (for example "Customers") so several searches can be told apart.
typeinput / buttonsearch on the input; button on Clear—type=search gives the search keyboard and native clearing affordances; type=button keeps Clear from submitting the form.
forlabel.forma-search__labelid of the input—Associates the visible label.
nameinputstring—Query parameter name on submission.
valueinputstringemptyThe current query when the page renders results for it.
autocompleteinputoffbrowser heuristicStops browser form history from competing with application suggestions.
placeholderinputstring—Optional hint about searchable fields; not a label.
role.forma-search__statusstatus—Polite live region so result-count and pending text are announced.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-searchBlock class—Root grid (the form) stacking label, control and status.
.forma-search__clearElement class—The Clear button, at least 4.5rem wide. Its action is application behavior.
.forma-search__controlElement class—Two-column grid: flexible input and auto-width Clear button, joined without a gap. One column at 30rem and below.
.forma-search__labelElement class—Compact visible label (0.8125rem, weight 650).
.forma-search__statusElement class—Result count or state text in secondary color at 0.75rem.
Keyboard interaction
KeysResult
EnterSubmits the search form (native implicit submission).
EscapeClears a type=search input in browsers that support it (native, browser-dependent).
TabMoves from the input to the Clear button.
Space / Enter on ClearActivates the button; the application must clear the input, update results and return focus to the input.
Events
EventDescription
submit / input / searchNative events from the form and search input. Debounced search-as-you-type is application behavior; Forma adds no events.

Form behavior

A GET form submits the query as name=value. The Clear button is type=button and does nothing without application code.

States

Search states
StateHow it is expressedPresentation
Emptyno valueLabel, empty input and Clear button; the status can be empty or state the total.
Resultsapplication text in .forma-search__statusA count such as "24 results".
Pendingapplication text in .forma-search__statusText such as "Searching…" while a request is outstanding.
No resultsapplication text in .forma-search__statusZero count with a recovery hint; keep the query in the field.
Focus:focus-visibleFoundation two-tone focus ring on the input or button.

Accessibility

Forma provides

  • Canonical markup provides a search landmark, a visible label tied to the input and a live status region.
  • The input and Clear button keep 44px minimum heights; at narrow widths the button stacks below so neither target shrinks.
  • Borders map to CanvasText in forced-colors mode.

Your application supplies

  • Update the status text for every result change, and throttle announcements while the user is typing.
  • After Clear, empty the input, restore results and return focus to the input.
  • Name each search landmark with aria-label when there is more than one on a page.
  • Cancel obsolete requests so stale results never replace newer ones.

Responsive behavior

  • The control is minmax(0, 1fr) auto, so the input shrinks before the Clear button and never overflows.
  • At 30rem (480px) and below the control becomes a single column with the Clear button under the input.
  • The root and control have min-inline-size: 0, so the component shrinks inside grid and flex parents.

Motion

  • No animation beyond the Clear button's shared hover and press background interpolation from the foundation layer. Result changes are not animated by Forma.

Usage guidance

Do

  • Keep the query visible after searching so users can refine it.
  • Say what was searched in no-result messages and suggest a next step.

Avoid

  • Using a placeholder as the only label.
  • Moving focus to results on every keystroke.

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.