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
- The user is choosing one value for a form field: use Combobox or Select.
- The user runs commands or jumps anywhere in the app by name: use Command palette.
- The search is one control among sort, filters and view options above a collection: compose it inside Collection toolbar and show active filters with Active filter summary.
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.
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.
<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
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.
<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.
Search in progress
The application is waiting for results. The status line says so in text, and the previous count is not shown as if it were current.
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.
<forma-search class="forma-component-tag">
<form class="forma-search" role="search" aria-label="Incidents" action="/incidents" method="get">
<label class="forma-search__label" for="search-pending-query">Search incidents</label>
<div class="forma-search__control">
<input id="search-pending-query" name="q" type="search" value="database failover" autocomplete="off" placeholder="Title, ID or service">
<button type="button" class="forma-search__clear">Clear</button>
</div>
<p class="forma-search__status" role="status">Searching…</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.
Mobile document search
Document search at phone width. The Clear button moves below the input so the query field keeps the full width.
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.
What changes at narrow widths
- At 30rem (480px) and below the control becomes one column: the input takes the full width and the Clear button sits beneath it.
- The input and button each keep a 44px minimum height for touch.
- type=search shows the search keyboard, whose action key submits the form.
- Long result-count messages wrap under the control; nothing scrolls horizontally.
<forma-search class="forma-component-tag">
<form class="forma-search" role="search" aria-label="Documents" action="/documents" method="get">
<label class="forma-search__label" for="search-mobile-query">Search documents</label>
<div class="forma-search__control">
<input id="search-mobile-query" name="q" type="search" value="retention policy" autocomplete="off">
<button type="button" class="forma-search__clear">Clear</button>
</div>
<p class="forma-search__status" role="status">7 documents</p>
</form>
</forma-search>
Click or tap the code once to select all of it, then copy.
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.
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.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
role | form | search | — | Makes the form a search landmark. Add aria-label when a page has more than one search. |
aria-label | form | string | — | Names the search landmark (for example "Customers") so several searches can be told apart. |
type | input / button | search on the input; button on Clear | — | type=search gives the search keyboard and native clearing affordances; type=button keeps Clear from submitting the form. |
for | label.forma-search__label | id of the input | — | Associates the visible label. |
name | input | string | — | Query parameter name on submission. |
value | input | string | empty | The current query when the page renders results for it. |
autocomplete | input | off | browser heuristic | Stops browser form history from competing with application suggestions. |
placeholder | input | string | — | Optional hint about searchable fields; not a label. |
role | .forma-search__status | status | — | Polite live region so result-count and pending text are announced. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-search | Block class | — | Root grid (the form) stacking label, control and status. |
.forma-search__clear | Element class | — | The Clear button, at least 4.5rem wide. Its action is application behavior. |
.forma-search__control | Element class | — | Two-column grid: flexible input and auto-width Clear button, joined without a gap. One column at 30rem and below. |
.forma-search__label | Element class | — | Compact visible label (0.8125rem, weight 650). |
.forma-search__status | Element class | — | Result count or state text in secondary color at 0.75rem. |
| Keys | Result |
|---|---|
| Enter | Submits the search form (native implicit submission). |
| Escape | Clears a type=search input in browsers that support it (native, browser-dependent). |
| Tab | Moves from the input to the Clear button. |
| Space / Enter on Clear | Activates the button; the application must clear the input, update results and return focus to the input. |
| Event | Description |
|---|---|
submit / input / search | Native 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
| State | How it is expressed | Presentation |
|---|---|---|
| Empty | no value | Label, empty input and Clear button; the status can be empty or state the total. |
| Results | application text in .forma-search__status | A count such as "24 results". |
| Pending | application text in .forma-search__status | Text such as "Searching…" while a request is outstanding. |
| No results | application text in .forma-search__status | Zero count with a recovery hint; keep the query in the field. |
| Focus | :focus-visible | Foundation 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.