Skip to content

Search Field

Get Ritla UI

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

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add search-field

    Also works with shadcn: npx shadcn@latest add @ritla/search-field

  2. Dependencies it brings

    @base-ui/react@phosphor-icons/react

  3. Or 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

search-field.tsx
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.

EnglishMirroredArabic
LTR →

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.

EnglishMirroredArabic
LTR →

API reference

SearchField

Also takes <input> props.

PropTypeDefaultDescription
labelReactNodeNoneFigma's Label.
variant"outline" | "minimal""outline"Figma's Style.
value / defaultValuestringNoneThe query.
onValueChange(value: string) => voidNoneOn every change, including picking a suggestion and clearing.
onClear() => voidNoneAfter the clear button empties the field.
loadingboolean | "skeleton"falseState = Loading: the spinner, keeping the query. "skeleton" is State = Skeleton: the whole field as a placeholder while the page loads, with aria-busy.
suggestionsstring[]NoneSuggestions shown as people type.
inlineCompletebooleanfalseState = Auto complete.
statusstringNoneThe result count or state, announced politely.
clearLabelstringNoneThe clear button's name. Default: “Clear search” in the page language.
helperText / error / disabled…NoneAs 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.

WhereUseNotes
Filtering a list or table on the pageSearch field, OutlineA boxed field above the list; results filter in place.
Toolbars, list headers, dense panelsSearch field, MinimalAn underline only; never inside a form.
The app header, searching everythingSearch barA 56 px rounded bar with the menu and up to two actions or the avatar.
Suggestions and results on desktopSearch view, modalOpens over the page from the bar or a shortcut.
Suggestions and results on mobileSearch view, full-screenTakes 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: Scoped placeholderPeople know what the field searches before typing.
Don't: Generic placeholder“Type here…” says nothing about what can be found.

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: Loading, query keptThe spinner shows work in progress; the query stays to refine.
Don't: Query clearedThe field empties and people forget what they searched for.

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.

NormalizeExampleWhy
Alef forms to a bare alefTyping احمد finds أحمدMost people skip the hamza when typing.
Taa marbuta and haa at the endTyping مدرسه finds مدرسةBoth endings are common in typed text.
Alef maqsura and yaa at the endTyping مستشفي finds مستشفىKeyboards and habits differ by country.
Diacritics and tatweel removedTyping كتاب finds كِتَاب and كتـابVowel marks and stretching aren't part of the word.
Arabic-Indic digits to 0123456789Typing ١٢٣ finds 123People type digits on either keyboard.

The field follows the reading direction

A merchant search in Arabic.

Do: RTL variantThe magnifier sits where the Arabic reader starts, the clear button at the end.
Don't: English variant with an Arabic queryThe magnifier and clear button are on the wrong sides, and the text keeps Latin fonts.

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.

KeyAction
ArrowDownArrowUpBetween suggestions.
EnterPicks the highlighted suggestion.
EscapeCloses the suggestions, then clears the query (the clear button is for pointer and touch).
TabArrowRightWith inlineComplete, at the end of the text: takes the faint completion.

ARIA

  • The region is role="search" and the input type="search" with a visible label; suggestions are a listbox tied 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 status to 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-16 like every field; suggestions in label-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.

  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)
  • R023Text inputs rendered LTR where Arabic input is expected