Search Field
A search field with the magnifier, a clear button once there is text and a loading spinner, with optional suggestions as you type. Boxed in pages and forms, underlined in toolbars and lists.
Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add search-fieldAlso works with shadcn:
npx shadcn@latest add @ritla/search-fieldDependencies it brings
@base-ui/react@phosphor-icons/reactOr copy by hand
Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.
Usage
import { SearchField } from "@/components/ui/search-field";<SearchField label="Search transactions" suggestions={merchants} onValueChange={setQuery} />Examples
Styles and states
variant: outline (boxed) or minimal (underlined; not inside forms). loading shows the spinner and keeps the query; loading="skeleton" stands in for the whole field while the page loads.
Inline completion
inlineComplete shows the rest of the first matching suggestion faintly after the text: press Tab (or the forward arrow) to take it, or keep typing.
API reference
SearchField
Also takes <input> props.
| Prop | Type | Default | Description |
|---|---|---|---|
label | ReactNode | None | Figma's Label. |
variant | "outline" | "minimal" | "outline" | Figma's Style. |
value / defaultValue | string | None | The query. |
onValueChange | (value: string) => void | None | On every change, including picking a suggestion and clearing. |
onClear | () => void | None | After the clear button empties the field. |
loading | boolean | "skeleton" | false | State = Loading: the spinner, keeping the query. "skeleton" is State = Skeleton: the whole field as a placeholder while the page loads, with aria-busy. |
suggestions | string[] | None | Suggestions shown as people type. |
inlineComplete | boolean | false | State = Auto complete. |
status | string | None | The result count or state, announced politely. |
clearLabel | string | None | The clear button's name. Default: “Clear search” in the page language. |
helperText / error / disabled | … | None | As on Input Field. |
Usage guidelines
Search helps people find what they want in a list or across the product. Which component to pick, what the placeholder says, what happens while people type, how search handles Arabic, and the checks before handoff.
1. Which search
Four components cover the places people search. Pick by where search sits and how much space the results need.
| Where | Use | Notes |
|---|---|---|
| Filtering a list or table on the page | Search field, Outline | A boxed field above the list; results filter in place. |
| Toolbars, list headers, dense panels | Search field, Minimal | An underline only; never inside a form. |
| The app header, searching everything | Search bar | A 56 px rounded bar with the menu and up to two actions or the avatar. |
| Suggestions and results on desktop | Search view, modal | Opens over the page from the bar or a shortcut. |
| Suggestions and results on mobile | Search view, full-screen | Takes the whole screen; the back arrow closes it. |
Do
- Keep search visible when it is the main task of the page.
- Use one search per scope: the header searches everything, a field above a list searches that list.
Don't
- Hide search behind an icon on a page built around finding things.
- Use the Minimal style inside a form.
2. Placeholder and scope
The placeholder says what gets searched: “Search transactions”, not just “Search”, when the scope isn't obvious. It disappears when people type, so it only describes the scope; the accessible name comes from the label you pass in code.
Say what is searched
The search above a transactions list.
Do
- Name the scope: Search transactions, Search merchants.
- Keep it short enough to fit on mobile.
- Give the field an accessible name even when no label is shown.
Don't
- Write instructions in the placeholder: “Type a name and press Enter”.
- Use vague text like “Type here…”.
- Promise things search can't do, like “Search anything”.
3. While people type
Show suggestions as people type, and results when they press Enter or pick one. Keep the query in the field while results load and after they appear, so people can refine it. The clear button appears once there is text; clearing restores the unfiltered view.
Keep the query while loading
Searching merchants.
Do
- Start suggesting after a character or two, and wait for a short pause in typing.
- Show the Loading state and keep the query while results load.
- Say when there are no results, and suggest what to try.
- Offer recent searches in the empty field.
Don't
- Clear the query when results appear.
- Make people press Enter before anything happens in a short list.
- Show an empty page with no message when nothing matches.
4. Arabic search
On Arabic screens use the RTL variants: the magnifier moves to the right and the clear button to the left. The query takes dir="auto", so English names typed into an Arabic search still read correctly. Matching Arabic well happens in the search backend: people type the same word in several spellings, and a plain text match misses them.
| Normalize | Example | Why |
|---|---|---|
| Alef forms to a bare alef | Typing احمد finds أحمد | Most people skip the hamza when typing. |
| Taa marbuta and haa at the end | Typing مدرسه finds مدرسة | Both endings are common in typed text. |
| Alef maqsura and yaa at the end | Typing مستشفي finds مستشفى | Keyboards and habits differ by country. |
| Diacritics and tatweel removed | Typing كتاب finds كِتَاب and كتـاب | Vowel marks and stretching aren't part of the word. |
| Arabic-Indic digits to 0123456789 | Typing ١٢٣ finds 123 | People type digits on either keyboard. |
The field follows the reading direction
A merchant search in Arabic.
Before handoff
- The right component for the place: field, bar or view.
- The placeholder names the scope, in both languages.
- Loading, no-results and recent-search states are designed.
- Arabic screens use RTL variants, and Arabic normalization is noted for the backend.
Accessibility
Keyboard
Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.
| Key | Action |
|---|---|
| ArrowDownArrowUp | Between suggestions. |
| Enter | Picks the highlighted suggestion. |
| Escape | Closes the suggestions, then clears the query (the clear button is for pointer and touch). |
| TabArrowRight | With inlineComplete, at the end of the text: takes the faint completion. |
ARIA
- The region is
role="search"and the inputtype="search"with a visible label; suggestions are alistboxtied to the input (Base UI). - The clear button is named “Clear search” in the page language and returns focus to the field.
- Pass the result count as
statusto have it announced politely: while suggestions are open, Base UI hides the rest of the page from screen readers, so a live region outside the field would go unheard.
Do
- An accessible name on every search: “Search transactions”.
- Announce the result count: pass
status, read politely. - Arrows move through suggestions, Enter picks, Escape closes.
- Name the clear button (“Clear search”) and return focus to the input.
Don't
- Move focus into the results while people type.
- Use the magnifier as the only label.
Arabic and RTL notes
Mirrors
- The magnifier sits at the start (the right), the clear button and spinner at the end (the left).
Does not mirror
- The magnifier, clear and spinner icons don't mirror.
- Numerals
- What people type stays as typed; show the result count in the page numerals (
formatNumber). - Arabic typography
label-16like every field; suggestions inlabel-14.- Mixed-direction text
- The query and suggestions take
dir="auto": an English merchant name in an Arabic UI runs left to right.
Do
- The RTL variant on Arabic screens.
- Normalize the query and the indexed text the same way.
- Search the Arabic and English names of the same thing: countries, products.
Don't
- An Arabic query in the English variant.
- Rely on an exact match for Arabic text.
Checks it passes
The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.