Form inputs

Combobox

<forma-combobox>

Searchable selection baseline that preserves direct text entry and native semantics.

Authoring tag
<forma-combobox>
Category
Form inputs
Behavior owner
Native baseline / Limen enhancement
Canonical source
patterns/combobox.html

Purpose

A combobox is a text input with suggestions: the user can type to narrow a list or enter a value directly. Forma's baseline is a native input linked to a datalist with the list attribute, so the browser supplies suggestion matching, the suggestion popup and keyboard selection with no script. .forma-combobox lays out the label, control, a decorative indicator and help text. Asynchronous suggestions, loading/no-result/error states, rich options and full WAI-ARIA combobox keyboard behavior are Limen/application enhancements layered on the same visual contract.

Use when

  • The list of values is long enough that typing to filter is faster than scrolling a Select.
  • Users may need to enter a value that is not in the list, such as a new tag or a free-form project name.
  • Suggestions help but are not the only acceptable answers.

Avoid when

  • The list is short and fixed and only listed values are valid: use Select or Choice group.
  • The user is searching a collection and expects results rather than a single value: use Search.
  • The user runs commands by name: use Command palette.
  • Several values must be picked as tokens: that multiselect needs Limen behavior and is not this baseline.

Behavior to know

  • The input always accepts typed text; a datalist only suggests.
  • Suggestion popup appearance and matching rules are browser-owned and vary by platform.
  • The application must validate that a typed value is acceptable; a datalist does not constrain submission.

Basic example

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

Canonical

Minimal combobox

Rendered from the canonical pattern file.

Type to filter available projects.

HTML · Minimal combobox Raw HTML for HTML · Minimal combobox
<forma-combobox class="forma-component-tag">
<div class="forma-combobox">
  <label for="combo-project">Project</label>
  <div class="forma-combobox__control">
    <input id="combo-project" name="project" list="project-options" autocomplete="off" placeholder="Search projects">
    <span class="forma-combobox__indicator" aria-hidden="true">⌄</span>
  </div>
  <datalist id="project-options">
    <option value="Architecture assessment"></option>
    <option value="Signal research"></option>
    <option value="Platform modernization"></option>
  </datalist>
  <p class="forma-combobox__help">Type to filter available projects.</p>
</div>
</forma-combobox>

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

Examples

Scenario

Label with new values allowed

Existing labels are suggested, but a new label can be typed and submitted as is. The help text says so and is linked with aria-describedby.

Choose an existing label or type a new one.

HTML · Label with new values allowed Raw HTML for HTML · Label with new values allowed
<forma-combobox class="forma-component-tag">
  <div class="forma-combobox">
    <label for="combobox-free-entry-label">Label</label>
    <div class="forma-combobox__control">
      <input id="combobox-free-entry-label" name="label" list="combobox-free-entry-options" autocomplete="off" aria-describedby="combobox-free-entry-help">
      <span class="forma-combobox__indicator" aria-hidden="true">⌄</span>
    </div>
    <datalist id="combobox-free-entry-options">
      <option value="bug"></option>
      <option value="customer-reported"></option>
      <option value="needs-design"></option>
      <option value="performance"></option>
    </datalist>
    <p class="forma-combobox__help" id="combobox-free-entry-help">Choose an existing label or type a new one.</p>
  </div>
</forma-combobox>

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

Scenario

Unrecognized value

Only listed cost centers are accepted. The application checked the typed value on submit, marked the input with aria-invalid and linked a validation message after the help text; the typed text is kept for correction.

Type to filter cost centers.

No cost center called "Marketting". Choose one from the list.

HTML · Unrecognized value Raw HTML for HTML · Unrecognized value
<forma-combobox class="forma-component-tag">
  <div class="forma-combobox">
    <label for="combobox-unrecognized-cost-center">Cost center</label>
    <div class="forma-combobox__control">
      <input id="combobox-unrecognized-cost-center" name="cost-center" list="combobox-unrecognized-options" autocomplete="off" value="Marketting" required aria-invalid="true" aria-describedby="combobox-unrecognized-help combobox-unrecognized-error">
      <span class="forma-combobox__indicator" aria-hidden="true">⌄</span>
    </div>
    <datalist id="combobox-unrecognized-options">
      <option value="Engineering"></option>
      <option value="Finance"></option>
      <option value="Marketing"></option>
      <option value="Operations"></option>
    </datalist>
    <p class="forma-combobox__help" id="combobox-unrecognized-help">Type to filter cost centers.</p>
    <p class="forma-validation-message" id="combobox-unrecognized-error">
      <span class="forma-validation-message__mark" aria-hidden="true">!</span>
      No cost center called "Marketting". Choose one from the list.
    </p>
  </div>
</forma-combobox>

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 assignee field

An assignee combobox at phone width. The input fills the width and the platform shows suggestions in its own UI.

Viewport width

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

What changes at narrow widths

  • The label, control and help stack in one column and the input fills the width with a 44px minimum height.
  • On touch devices suggestions usually appear in the keyboard's suggestion strip or a platform list above the keyboard; this is browser-owned and varies.
  • The indicator is absolutely positioned at the inline end and does not take width; very long typed values can run beneath it.
  • Help text wraps below the control; nothing scrolls horizontally.
HTML · Mobile assignee field Raw HTML for HTML · Mobile assignee field
<forma-combobox class="forma-component-tag">
  <div class="forma-combobox">
    <label for="combobox-mobile-assignee">Assign to</label>
    <div class="forma-combobox__control">
      <input id="combobox-mobile-assignee" name="assignee" list="combobox-mobile-assignee-options" autocomplete="off" aria-describedby="combobox-mobile-assignee-help">
      <span class="forma-combobox__indicator" aria-hidden="true">⌄</span>
    </div>
    <datalist id="combobox-mobile-assignee-options">
      <option value="Amara Okafor"></option>
      <option value="Jonas Lindqvist"></option>
      <option value="Priya Raman"></option>
    </datalist>
    <p class="forma-combobox__help" id="combobox-mobile-assignee-help">Type a name. Leave empty to keep the item unassigned.</p>
  </div>
</forma-combobox>

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.

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
listinputid of a datalist—Connects the native suggestion list. Required for the no-script baseline.
forlabelid of the input—Associates the visible label.
nameinputstring—Form field name; the typed text is what is submitted.
autocompleteinputoffbrowser heuristicStops the browser's form history from mixing with the datalist suggestions.
valueoptionstring—Suggested value inside the datalist.
placeholderinputstring—Optional example text; never a replacement for the label.
requiredinputbooleanabsentNative constraint against an empty value; does not require a listed value.
aria-describedbyinputid list—Links the help text and any validation message.
aria-invalidinputtrueabsentSet by the application when the typed value is not accepted.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-comboboxBlock class—Root grid (0.5rem gap). A direct child label gets the compact field-label style.
.forma-combobox__controlElement class—Positioning wrapper around the input and indicator.
.forma-combobox__helpElement class—Help text in secondary color at 0.75rem. Link it with aria-describedby.
.forma-combobox__indicatorElement class—Decorative glyph pinned to the inline end and vertically centered; pointer-transparent. Mark it aria-hidden="true".
Keyboard interaction
KeysResult
TypingFilters the native suggestion list (matching rules are browser-owned).
ArrowDown / ArrowUpOpens and moves through suggestions in browsers that show a datalist popup.
EnterAccepts the highlighted suggestion; with no suggestion open, submits the form natively.
EscapeCloses the suggestion popup in most browsers.
Limen enhancementA custom listbox must implement the WAI-ARIA combobox pattern (aria-expanded, aria-activedescendant, Home/End) in application code; Forma provides none of it.
Events
EventDescription
input / changeNative input events. Choosing a datalist suggestion fires input with the new value. Forma adds none.

Form behavior

A native text input: submits whatever text is present, whether or not it matches a suggestion. List membership must be validated by the application.

States

Combobox states
StateHow it is expressedPresentation
Emptyno valueLabel, input and help text; optional placeholder.
Suggestingbrowser datalist popupBrowser-rendered list of matching suggestions; not styled by Forma.
Focus:focus-visibleFoundation two-tone focus ring on the input.
Invalidaria-invalid="true" plus a linked .forma-validation-messageError text with a non-color mark below the help text.
Loading / no results / errorapplication-supplied help or status textOnly exists with a Limen enhancement for asynchronous suggestions; express it as text, not only as a spinner.

Accessibility

Forma provides

  • The no-script baseline uses a labelled native input and datalist, which browsers expose as a combobox with suggestions.
  • Typed entry is always available, so the control never requires pointer use or a popup.
  • The indicator is decorative and hidden from assistive technology.

Your application supplies

  • Link the help text with aria-describedby; the canonical pattern does not.
  • Validate list membership and explain rejected values with a Validation message.
  • When replacing the datalist with a custom popup, implement the full WAI-ARIA combobox pattern, announce result counts and cancel obsolete asynchronous requests.
  • Keep composition (IME) input safe: do not filter or submit on keystrokes during composition.

Responsive behavior

  • Single-column grid; the input fills the container width.
  • The indicator is positioned over the input's inline end without reserving padding, so very long typed text can pass beneath it.
  • No breakpoints; suggestion UI on touch devices is platform-owned.

Motion

  • No animation: Forma does not transition the combobox or its indicator. The native suggestion popup's appearance is browser-controlled.

Usage guidance

Do

  • Say in the help text whether new values are allowed.
  • Keep suggestion values short and distinct.

Avoid

  • Assuming a datalist restricts the submitted value.
  • Using the indicator glyph as the only sign that suggestions exist; the help text should say so.

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.