Cloaked Design SystemForms
SearchField
A controlled search input with search icon, return-key callback, optional loading indicator, and value-dependent clear action.
Implementation previewCOMPLETE STORYBOOK REFERENCE
5 storiesEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Playground selectedOpen canvas
Example source
packages/design-system/src/components/forms/SearchField/SearchField.stories.tsxExport PlaygroundImplementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.
Stories + source JSON ↗Local specification source status: preview. Implementation preview pending sign-off.
A controlled search input with search icon, return-key callback, optional loading indicator, and value-dependent clear action.
Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off
Implementation API 1 entry point · source-derived preview
Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.
import { SearchField } from '@cloakedinc/design-system';SearchFieldSearchFieldProps
packages/design-system/src/components/forms/SearchField/SearchField.tsx:64
| Prop | Type | Presence | Notes |
|---|---|---|---|
value | string | Required | Query text to display; a non-empty value is also what reveals the clear action. |
onChange | ((value: string) => void) | undefined | Optional | Called with the new text on each keystroke, and with `''` when the clear action fires. |
onSearch | ((value: string) => void) | undefined | Optional | Called when the search key is pressed. |
enterBehavior | InputEnterBehavior | undefined | Optional | Return-key behavior. Defaults to search callback behavior.Source default: 'callback' |
enterKeyHint | InputEnterKeyHint | undefined | Optional | Native on-screen keyboard return key hint. Defaults to `search`.Source default: 'search' |
onClear | (() => void) | undefined | Optional | Called after the clear action resets the query. |
placeholder | string | undefined | Optional | Placeholder text. Defaults to `Search`.Source default: 'Search' |
size | InputSize | Required | Field height and type scale, shared with the underlying `Input`. Required — there is no default. |
loading | boolean | undefined | Optional | Shows a spinner in the trailing slot. Typing and clearing stay available. |
disabled | boolean | undefined | Optional | Blocks typing and the clear action. |
surface | InputSurface | undefined | Optional | Container background treatment.Source default: 'default' |
autoCorrect | "on" | "off" | undefined | Optional | Native autocorrect hint. Defaults to `off` so search fields stay quiet.Source default: 'off' |
autoCapitalize | "none" | "on" | "off" | "sentences" | "words" | "characters" | undefined | Optional | Native autocapitalize hint. Defaults to `off` so search fields stay quiet.Source default: 'off' |
spellCheck | boolean | undefined | Optional | Native spellcheck hint. Defaults to `false` so search fields stay quiet.Source default: false |
ariaLabel | string | undefined | Optional | Accessible name when no visible label is associated with the field.Source default: 'Search' |
ariaControls | string | undefined | Optional | ID of the result list controlled by this search field. |
className | string | undefined | Optional | |
style | React.CSSProperties | undefined | Optional | |
testId | string | undefined | Optional | Optional test selector. Clear action derives `${testId}-clear`. |
Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.
Overview
A dedicated search input — a leading search icon, an inline loading spinner, and a clear
action that appears once there is a query.
When to use
Reach for SearchField when the control's whole job is to filter or query — a broker search,
a website picker, a list filter. It composes Input with type="search", defaults
autocorrect/autocapitalize/spellcheck off so the field stays quiet, fires onSearch on the
return key, and gives you the clear affordance for free.
- Just need a single-line text value (email, name, a bare
type="search"box) with no clear button or search-key semantics? UseInputdirectly. - Need the query to also drive a results dropdown the user picks from? Use
Autocomplete—SearchFieldis the search primitive inside it, so don't rebuild the dropdown around a bareSearchField.
In-app it backs the automations website search (WebsiteSearchView) and the add-to-dashboard
picker (AddToDashboardBottomSheet).
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- control
- Label
- Control
- Description
- Input shell that owns size, surface, focus, disabled state, and slots.
- Id
- search-icon
- Label
- Search icon
- Description
- Persistent leading icon that communicates search intent.
- Id
- field
- Label
- Search input
- Description
- Native search field that owns the controlled query and return-key behavior.
- Id
- loading-indicator
- Label
- Loading indicator
- Description
- Optional labelled trailing spinner shown while results update.
- Id
- clear-action
- Label
- Clear action
- Description
- Value-dependent trailing button that resets the query.
Allowed Design Choices
- Variants
- Base
- Label
- Base
- Description
- One search treatment configured through independent size and surface axes.
- Sizes
- Sm
- Label
- Small
- Md
- Label
- Medium
- Surfaces
- Default
- Label
- Default
- Description
- Uses the semantic input container.
- Raised
- Label
- Raised
- Description
- Uses the raised surface when the field sits directly on the page canvas.
Variants
- Id
- base
- Label
- Base
- Description
- Search-specific composition of Input with fixed leading and conditional trailing affordances.
- Platforms
- ios
- android
- web
Sizes
- Id
- sm
- Label
- Small
- Description
- 40-unit compact search field.
- Id
- md
- Label
- Medium
- Description
- 56-unit standard search field.
Measurements
- Id
- small-height
- Label
- Small control height
- Kind
- exact
- Token
- --cds-size-40
- Value
- 40
- Unit
- px
- Applies To
- control
- sm
- Id
- medium-height
- Label
- Medium control height
- Kind
- exact
- Token
- --cds-size-56
- Value
- 56
- Unit
- px
- Applies To
- control
- md
- Id
- web-input-font-size
- Label
- Web search input font size
- Kind
- exact
- Token
- --cds-type-body-size
- Value
- 16
- Unit
- px
- Applies To
- field
- sm
- md
- Notes
- Web keeps the compact field at the 16px anti-zoom floor.
Layout
- Alignment
- Search icon, native input, loading indicator, and clear action share the control center line.
- Flow
- Persistent search icon, flexible input, optional loading indicator, then optional clear action.
- Notes
- Loading and clear may coexist; each occupies its own trailing slot.
- Use Autocomplete when the search field must present selectable results.
Typography And Color
- Typography
- Label
- Search query
- Description
- Use body text on web to prevent focused-input viewport zoom.
- Token
- --cds-type-body-size
- Colors
- Label
- Default surface
- Description
- Use the semantic input container.
- Token
- --cds-input-container
- Label
- Raised surface
- Description
- Use the raised semantic surface.
- Token
- --cds-bg-surface
- Label
- Query
- Description
- Use primary text emphasis.
- Token
- --cds-text-primary
- Label
- Placeholder and icons
- Description
- Use secondary text emphasis.
- Token
- --cds-text-secondary
States
- Id
- empty
- Label
- Empty
- Description
- Shows the placeholder and no clear action.
- Id
- filled
- Label
- Filled
- Description
- Shows the controlled query and the clear action.
- Id
- loading
- Label
- Loading
- Description
- Shows a labelled trailing spinner while preserving query editing.
- Id
- focused
- Label
- Focused
- Description
- Accepts search-key submission; the inherited Input control has no focus ring, since the design system targets a touch surface.
- Id
- disabled
- Label
- Disabled
- Description
- Blocks editing and clearing and dims the entire control.
Behavior
- Label
- Controlled editing
- Description
- Request query changes on each edit while the parent owns the rendered value.
- Label
- Search return key
- Description
- Default to callback behavior and a search return-key hint, emitting the current query.
- Label
- Clear
- Description
- Request an empty query before invoking the optional clear callback.
- Label
- Quiet typing defaults
- Description
- Default autocorrect, autocapitalization, and spellcheck off for search terms.
Accessibility
- Label
- Search role and name
- Description
- Expose native searchbox semantics and require an accessible name.
- Label
- Controlled results
- Description
- Associate the input with a result container through controls when one exists.
- Label
- Clear action
- Description
- Name the clear button independently and give it a derived stable test identifier.
Content Adaptation
- Label
- Placeholder
- Description
- Describe what can be searched rather than using generic instructional copy.
- Label
- Long queries
- Description
- Let the native single-line input scroll horizontally without displacing fixed affordances.
Motion Haptics
- Motion
- Label
- Trailing affordances
- Description
- Add or remove loading and clear affordances without changing control height.
- Haptics
- Label
- No intrinsic feedback
- Description
- Typing, search submission, and clearing do not request design-system haptics.
Platform Differences
- Platforms
- web
- Description
- Small search fields retain a 16px input font instead of the 14px body-small token value.
- Rationale
- WKWebView zooms focused inputs below 16px; the floor prevents a viewport jump while preserving the compact 40px shell.