ComponentsEnterpriseSearchField

SearchField

SearchField captures and submits a query without owning suggestions or results.

Controlled query3 variants3 sizesLoadingResult summary

Overview

Use SearchField to find content in a page, collection, or remote data set when the application owns result retrieval and presentation.

Project search

Live preview

Edit the query, press Enter, clear it, or use the explicit submit control.

Search by name, owner, or project ID.24 results
ProjectSearch.tsx
tsx
import { SearchField } from 'omverse-ui'
 
<SearchField
label="Search projects"
value={query}
onValueChange={setQuery}
onSearch={runSearch}
resultText="24 results"
showSubmitButton
/>

Anatomy

SearchField combines a search affordance, editable query, clear and optional submit controls, plus guidance or live result context.

⌕migration×→
Search by name or ID.24 results
12345
  1. 1
    Search icon

    Identifies the field purpose without replacing its label.

  2. 2
    Query input

    Captures free-form search terms.

  3. 3
    Clear control

    Empties a non-empty query and retains focus.

  4. 4
    Submit control

    Explicitly runs search when needed.

  5. 5
    Search context

    Shows guidance and a live result summary.

When to use

Use SearchField when people know terms that identify content and results are presented elsewhere.

Recommended

  • Search a collection

    Find projects, people, events, or records using recognizable terms.

  • Submit remote queries

    Use explicit submission when requests are expensive or intentional.

  • Summarize results

    Keep a concise result count connected to the current query.

When not to use

Use a selection or command pattern when the field must own suggestions or trigger application actions.

Avoid

  • Do not select values

    Use Combobox when a result becomes a form value.

  • Do not execute commands

    Use CommandBar for searchable actions and navigation.

  • Do not replace filters

    Use FilterBar for structured facets and governed conditions.

Variants

Three treatments and sizes let SearchField fit standalone pages, grouped forms, and compact productivity surfaces.

Outlined

Default boundary for independent search.

Filled

Tonal field within grouped surfaces.

Underlined

Restrained treatment for embedded search.

Sizes

Small, medium, and large maintain predictable controls.

States

SearchField coordinates query entry and resolution feedback while applications own the result lifecycle.

StateTriggerVisual responseInteraction
EmptyNo querySearch icon and placeholderReady for input
PopulatedQuery enteredQuery and clear controlEdit, clear, or submit
FocusedInput receives focusPrimary border and ringText entry active
LoadingSearch resolvingProgress iconQuery remains visible
ResultsResponse availableLive result summaryResults remain application-owned
DisabledSearch unavailableReduced emphasisNot operable

Behavior

SearchField owns query mechanics while debouncing, network requests, routing, result ranking, and analytics remain application concerns.

Submit

Enter and the optional submit control call onSearch.

Clear

Escape or clear empties a populated query and restores input focus.

Progress

Loading replaces clear with a non-blocking progress indicator.

Result summary

Result text uses a polite live status.

Accessibility

SearchField retains native search input behavior with persistent labeling and connected search feedback.

KeyAction
EnterSubmits the current query.
EscClears a populated query when clearable.
TabMoves through input and visible action controls.
  • Provide a visible label or an explicit aria-label.
  • Name clear and submit controls independently from their icons.
  • Announce result counts politely without moving focus.
  • Do not announce loading continuously during every keystroke.
  • Keep result content after the field in a logical reading order.
  • Use Combobox semantics instead when suggestions are selectable.

Content guidelines

Labels, placeholders, and result summaries should communicate scope without prescribing overly specific queries.

Name the scope

Identify what can be searched.

ExampleSearch projects

Offer useful terms

Describe supported identifiers in helper text.

ExampleSearch by name, owner, or project ID.

Keep placeholders short

Use a natural prompt when the label is already visible.

ExampleName or project ID

Quantify results

Use concise localized summaries.

Example24 results

Examples

Controlled state supports remote search while loading and result feedback remain aligned with the query.

Remote audit search

Live preview
Search actor, action, or resource.Searching…
AuditSearch.tsx
tsx
<SearchField
aria-label="Search audit events"
value={query}
onValueChange={setQuery}
onSearch={() => refetch()}
loading={queryState.isFetching}
resultText={queryState.data ? `${queryState.data.total} events` : undefined}
/>

Props / API

SearchField extends native input attributes except values, change, type, and size replaced by its controlled API.

Props

PropTypeDefaultDescription
valuestringundefinedControlled query.
defaultValuestring''Initial uncontrolled query.
onValueChange(value: string) => voidundefinedRuns whenever the query changes.
onSearch(value: string) => voidundefinedRuns when Enter or submit activates search.
onClear() => voidundefinedRuns after the clear control empties the query.
labelReactNodeundefinedVisible field label.
helperTextReactNodeundefinedSupporting instruction below the field.
resultTextReactNodeundefinedLive result summary.
loadingbooleanfalseShows query resolution progress.
clearablebooleantrueShows clear when the query has content.
showSubmitButtonbooleanfalseShows an explicit search button.
variant'outlined' | 'filled' | 'underlined''outlined'Controls field treatment.
size'sm' | 'md' | 'lg''md'Controls height, spacing, and type.