SearchField
SearchField collects one native search query with accessible clear, deliberate Enter events, and consumer-owned results.
Overview and decision boundary
Use SearchField for one free-form query that needs accessible clear and explicit Enter search behavior.
Do not add results, suggestions, requests, debounce, filtering, ranking, routing, global shortcuts, history, analytics, or product entities.
Submit one query; results and requests stay in the product.
Searching activity
import { SearchField } from '@nerio-ui/ui/client';<SearchField label="Search projects" name="query" autoComplete="off" onSearch={(query) => runSearch(query)}/>Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add search-fieldimport { SearchField } from '@nerio-ui/ui/client';Usage
import { SearchField } from '@nerio-ui/ui/client';<SearchField label="Search projects" name="query" autoComplete="off" onSearch={(query) => runSearch(query)}/>Variants
| Variant | Purpose |
|---|---|
sm | Compact size for dense layouts and inline use. |
md | Default size for most product surfaces. |
lg | Larger size for prominent local actions. |
LTR | LTR is part of the public component contract. |
RTL | RTL is part of the public component contract. |
Anatomy
| Slot | Purpose |
|---|---|
root / label | Field root and visible native label. |
input-group / input | Shared surface around one native search input. |
search-icon | Decorative default or consumer-provided search icon. |
actions / clear | Localizable clear action that restores input focus. |
loading | Localizable default status or consumer loading-indicator slot. |
description / message | Associated help or validation content. |
States
| State | Behavior |
|---|---|
Value | One controlled or uncontrolled string query. |
Search | Enter emits onSearch without preventing native form submission. |
Loading | Presentation only; requests remain consumer-owned. |
Disabled / read-only | Preserves native semantics and prevents clearing. |
Required / invalid | Participates in forms and associates validation content. |
Motion
- shared form-control transitions
- reduced-motion immediate transition
Accessibility
- Uses a native input type=search associated with a visible Field label, description, and message.
- Supports one controlled or uncontrolled string value without mirrored state; native form identity and reset remain intact.
- The localizable clear action is a native button, is unavailable while disabled or read-only, and restores focus to the same input node.
- Enter emits one Nerio-owned search event without preventing native form submission; IME composition is not treated as a search.
- The search icon is decorative. The default loading indicator exposes a localizable status through loadingLabel; a custom loadingIndicator must provide equivalent semantics.
- Disabled, read-only, required, invalid, autofill, LTR, RTL, narrow-container, and long-label behavior preserve the shared form contracts.
- Results, suggestions, requests, debounce, filtering, ranking, routing, global shortcuts, history, analytics, and product search workflows remain consumer or Pro responsibilities.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Props | Purpose |
|---|---|
value / defaultValue / onValueChange | One controlled or uncontrolled query. |
onSearch | Receives the current query and an IME-safe Enter event detail. |
clearLabel | Localizable accessible name for the icon-only clear action. |
loading / loadingLabel | Default localizable loading status presentation. |
searchIcon / loadingIndicator | Meaningful structural customization slots. |
name / form / required / autoComplete | Native form identity, reset, and autofill hints. |
disabled / readOnly / invalid | Native interaction and Field validation states. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | search-field installs 3 source files into the configured components directory. |
Base UI | No interactive primitive required. |
Registry dependencies | button, field, input-group, spinner |
Package dependencies | @nerio-ui/adapters, @base-ui/react, clsx, react, tailwind-merge, tailwindcss |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use SearchField for one free-form query that needs accessible clear and explicit Enter search behavior.
Do / do not
Do
Use SearchField for one free-form query that needs clear and explicit search behavior.
Do not
Put results, requests, debounce, filtering, ranking, routing, global shortcuts, history, analytics, or product entities in SearchField.
Related components
Tokens
These are the primary customization points. Override semantic or component tokens instead of changing component source.
| Token | Purpose |
|---|---|
--n-input-height-sm | Public customization point for this component contract. |
--n-input-height-md | Public customization point for this component contract. |
--n-input-height-lg | Public customization point for this component contract. |
--n-input-radius | Public customization point for this component contract. |
--n-input-background | Public customization point for this component contract. |
--n-input-background-hover | Public customization point for this component contract. |
--n-input-border | Public customization point for this component contract. |
--n-input-border-hover | Public customization point for this component contract. |
--n-input-border-focus | Public customization point for this component contract. |
--n-input-border-danger | Public customization point for this component contract. |
--n-input-placeholder | Public customization point for this component contract. |
--n-input-foreground | Public customization point for this component contract. |
--n-input-disabled-background | Public customization point for this component contract. |
--n-input-disabled-foreground | Public customization point for this component contract. |
--n-input-addon-foreground | Public customization point for this component contract. |
--n-input-addon-gap | Public customization point for this component contract. |
--n-input-addon-padding-inline | Public customization point for this component contract. |
--n-focus-ring | Public customization point for this component contract. |