Skip to content
omaris

Navigation

Search Bar

MD3 search — the bar and the view it opens into.

import { SearchBar } from 'omaris'
Learn

Examples

Basic

Suggestions arrive as data. filter={false} when they come back already filtered — from a server, or from your own ranking.

<script lang="ts">	import { SearchBar } from 'omaris';​	let query = $state('');​	const RECENT = [		{ value: 'inv-4021', label: 'Invoice 4021', supporting: 'Kurdistan Roasters', group: 'Recent' },		{ value: 'inv-4022', label: 'Invoice 4022', supporting: 'Dijla Grocers', group: 'Recent' },		{ value: 'erbil', label: 'Erbil warehouse', supporting: '2 open orders', group: 'Places' }	];</script>​<div class="w-full max-w-md">	<SearchBar bind:value={query} suggestions={RECENT} placeholder="Search orders and places" /></div>

Views

auto docks a panel under the bar on a wide screen and goes full screen below the breakpoint. Force either when you know which one you want.

<script lang="ts">	import { SearchBar } from 'omaris';​	const SUGGESTIONS = [		{ value: 'a', label: 'Baghdad' },		{ value: 'b', label: 'Basra' },		{ value: 'c', label: 'Erbil' }	];</script>​<div class="flex w-full max-w-md flex-col gap-4">	<SearchBar view="docked" placeholder="Docked" suggestions={SUGGESTIONS} />	<SearchBar view="fullscreen" placeholder="Full screen" suggestions={SUGGESTIONS} /></div>

Variants and loading

loading swaps the trailing control for a spinner while results are in flight — for suggestions that come back from a server.

 
<script lang="ts">	import { SearchBar } from 'omaris';</script>​<div class="flex w-full max-w-md flex-col gap-4">	<SearchBar variant="filled" placeholder="filled" />	<SearchBar variant="outlined" placeholder="outlined" size="sm" />	<SearchBar variant="elevated" placeholder="elevated" loading /></div>

When to use it

Use it for

  • Search across the app (an order, a customer, a page) from the search slot of a Top App Bar. On a wide screen a panel docks under it; on a phone a tap opens a full search screen.
  • Results from a server. Set filter={false} so nothing is re-filtered locally, loading while the request is out, or use the results snippet for rows of your own.
  • A bar over a map or a canvas: variant="elevated".
  • Suggestions that open the best match on Enter. The first row is highlighted as soon as there is a query.

Not for

  • Filtering a table or list in place → a Text Field with a magnifier in start and clearable.
  • Choosing a value for a form field → Combobox.
  • Narrowing by category → filter Chips.
  • A settings page with sections → Toc.

Do

  • Handle both onsearch for Enter and onselect for a row. Both expect to go somewhere.
  • Show recent searches as suggestions while the query is empty, so the view is not blank on open.
  • Set autoHighlight={false} on a full-text search, where Enter means "search for this" rather than "open the best guess".
  • Put a menu button in leading when it sits in the app bar of a layout whose drawer is modal.

Don't

  • Put two on one screen. The global one is the pill; a page's filter is a Text Field.
  • Leave filter on for server results. Ranked rows get filtered again and the ranking is lost.
  • Send thousands of suggestions. Cap them at the source; the view is a short list.
Pairs with Top App Bar Text Field Combobox List Avatar Empty

Quick reference

variant
  • filled (default)
  • outlined
  • elevated
size
  • sm
  • md (default)
  • lg

API

SearchBar

MD3 search — the bar and the view it opens into.

The bar is the pill that sits in a top app bar: a leading icon (or a menu button), the query, and whatever belongs at the end — an avatar, a mic, a filter. Focus it and it becomes the search view, which is the part most implementations skip and the part that makes search feel native:

- On a phone the bar is the button that opens the search screen: one tap and the screen fades up over the page, with the field focused and the keyboard already up. It never sits there half-open with a caret in a pill and no results — the tap that focuses it is the tap that opens the screen. - On a wide screen it stays put and drops a docked panel underneath, which is what a dashboard wants — the page stays visible behind it. - view="auto" picks between the two on the viewport, so one bar is right on both.

Results can be handed over as suggestions — filtered locally as you type, or left alone with filter={false} when they come from a server — or drawn from scratch with the results snippet. Either way the arrow keys walk them, Enter takes the highlighted one, Escape backs out, and the field carries the combobox semantics a screen reader needs.

The first result is highlighted the moment there is a query, so Enter opens the obvious answer without arrowing down to it first — the way the address bar behaves. autoHighlight={false} restores the plain behaviour, where Enter searches for what was typed.

import { SearchBar } from 'omaris'

Parts

Every element this renders is reachable from outside. Pass Tailwind for one part as classes={{ part: '…' }}; class covers the root and is merged last, so it always wins.

root
No description in the source yet.
input
No description in the source yet.
icon
A static icon slot — the magnifier, usually.
action
A pressable one — back, clear, mic.
view
No description in the source yet.
viewHeader
The field row inside the view.
results
Everything under the field, in either view.
docked
The docked panel a wide screen gets instead. It starts at the bar's own width and may grow with its content, but only so far — a dropdown three times the width of the field it hangs off no longer reads as belonging to it.
body
The column inside the view: field, results, footer.
surface
No description in the source yet.
option
No description in the source yet.
group
A non-interactive heading above a run of options.
description
No description in the source yet.
check
No description in the source yet.
empty
"No results", "Searching…".
highlight
The part of a label that matched what was typed.

Props

value bindable

Defaults to ''

string

The query. Bindable.

open bindable

Defaults to false

boolean

Whether the search view is showing. Bindable.

placeholder

Defaults to 'Search'

string
variant

Defaults to 'filled'

SearchBarVariant
filled
MD3's default: a tinted pill with no border.
outlined
elevated
Floating over content — a map, a hero image.
size

Defaults to 'md'

SearchBarSize
sm
md
lg
view

Defaults to 'auto'

SearchBarView

Which view focusing the bar opens.

breakpoint

Defaults to 768

number

Viewport width, in px, under which auto goes full screen.

suggestions

Defaults to []

SearchSuggestion[]

Rows to show under the field.

filter

Defaults to true

boolean

Filter suggestions against the query here. Off when they arrive already filtered.

autoHighlight

Defaults to true

boolean

Highlight the first result as soon as there is a query, so Enter takes it without a trip through the arrow keys. Turn it off where Enter should search for what was typed rather than open the best guess.

loading

Defaults to false

boolean

Spinner in the field.

disabled

Defaults to false

boolean
emptyText

Defaults to 'No results'

string

Text when a query matches nothing.

onsearch
(value: string) => void

Fires on Enter, with the query.

onselect
(suggestion: SearchSuggestion) => void

Fires when a suggestion is taken.

onclear
() => void
onopen
(open: boolean) => void

Fires as the view opens and closes.

class
string
classes
SearchBarClasses

Per-part Tailwind overrides. class still covers the root.

leading
Snippet

Leading slot. Defaults to a magnifier — pass a menu button instead.

trailing
Snippet

Trailing slot — an avatar, a mic, a filter button.

results
Snippet

The whole result area, in place of suggestions.

footer
Snippet

Pinned under the results — "see all", a keyboard hint.