Primitive contract

SearchField

Defines a visible-label search field, accessible clear action, result-status region, no-results recovery, and error association without exporting filtering behavior.

Labelled local filtering control · @sanchika/primitives

Purpose and semantics

Defines a visible-label search field, accessible clear action, result-status region, no-results recovery, and error association without exporting filtering behavior.

Recommended semantic: Use a role=search form with a visible label, native input type=search, button type=button, and a separate role=status result region.

Anatomy

root

Search form or labelled field group.

label

Required visible label.

input wrapper

Positions input, icon, and clear action.

search icon

Decorative region hidden from assistive technology.

input

Native search input.

clear button

Named explicit reset command.

hint

Optional local-boundary or filtering guidance.

result status

Polite atomic result announcement.

error

Visible associated error message.

Finite variants and important states

Variant · size: sm, md, lg
Required states: default, focus-visible, has-value, filtering, results, no-results, disabled, error
Class hooks: .sk-search-field · .sk-search-field__control · .sk-search-field__icon · .sk-search-field__clear · [data-sk-result-status] · [data-sk-search-error]

Composed synthetic exemplar

Rendered state matrix

SearchField: 8 required states

Each specimen starts from the package-owned example and contract state inventory. Simulated pointer and focus frames are labelled; consumers still verify real interaction in context.

defaultSettled and available for its documented job.

focus visibleKeyboard focus remains explicit and independent of motion.

has valueThe has value contract remains visible and inspectable.

filteringThe filtering contract remains visible and inspectable.

resultsThe results contract remains visible and inspectable.

no resultsThe entered filter remains visible with a direct reset path.

disabledUnavailable with its reason preserved in nearby text.

errorThe failure and recovery path remain visible together.

Accessibility and consumer responsibility

Keyboard and screen reader

Keep native input editing
Consumer may clear on Escape only when a value exists
Clear button retains focus or returns it to input
Do not steal focus while filtering
Visible associated label
Accessible clear-button name
Polite atomic settled result count
Associate hint and error
Avoid duplicate native and custom clear controls

Consumer owns

Implement local filtering and Escape/clear behavior
Restore the complete list
Debounce or settle announcements
Handle native search affordance
Keep disabled clear inactive

Mobile

Control fills available width
Label, hint, result, and error wrap
Clear target remains reachable without overlap

Reduced motion and forced colors

No override is required.

Input and clear boundaries use system colors
Search state remains visible in text

Compact API reference

Package: @sanchika/primitives
CSS: @sanchika/primitives/styles.css
Contract: primitiveSpecs.find((contract) => contract.name === "SearchField")
Primary class: .sk-search-field