Navigation

Command Palette

⌘K — a search field over every action in the app, opened from anywhere.

import { CommandPalette } from 'omaris'

Examples

Basic

Groups of rows, each with a label and optionally an icon, a shortcut, a description or keywords. Type to fuzzy-match — "nwis" finds "New issue". hotkey is ⌘J here because this site already answers to ⌘K.

Last run: nothing yet

1<script lang="ts">2	import { Button, CommandPalette, Kbd, Text, type CommandGroup } from 'omaris';34	let open = $state(false);5	let ran = $state('nothing yet');67	const items: CommandGroup[] = [8		{9			heading: 'Go to',10			items: [11				{ id: 'dashboard', label: 'Dashboard', icon: home, onselect: () => (ran = 'Dashboard') },12				{ id: 'orders', label: 'Orders', icon: box, onselect: () => (ran = 'Orders') },13				{14					id: 'settings',15					label: 'Settings',16					keywords: ['preferences', 'account', 'profile'],17					icon: gear,18					shortcut: 'mod+,',19					onselect: () => (ran = 'Settings')20				}21			]22		},23		{24			heading: 'Actions',25			items: [26				{27					id: 'new-order',28					label: 'New order',29					description: 'Start a blank order',30					icon: plus,31					shortcut: 'mod+shift+o',32					onselect: () => (ran = 'New order')33				},34				{35					id: 'new-issue',36					label: 'New issue',37					icon: plus,38					shortcut: 'c',39					onselect: () => (ran = 'New issue')40				}41			]42		}43	];44</script>4546{#snippet home()}47	...48{/snippet}49{#snippet box()}50	...51{/snippet}52{#snippet gear()}53	...54{/snippet}55{#snippet plus()}56	...57{/snippet}5859<div class="flex flex-col items-center gap-2">60	<Button variant="outlined" onclick={() => (open = true)}>61		Search commands62		<Kbd keys="mod+j" size="sm" variant="flat" />63	</Button>64	<Text variant="body-sm" tone="muted">Last run: {ran}</Text>65</div>6667<CommandPalette bind:open {items} hotkey="mod+j" />

Pages and recents

A row with children is a page: it opens as its own list, named by a chip in the field; Backspace on an empty field goes back. A query from the top reaches into every page — type "dark". recentKey remembers what was chosen.

Last run: nothing yet

1<script lang="ts">2	import { Button, CommandPalette, Text, type CommandGroup } from 'omaris';34	let open = $state(false);5	let ran = $state('nothing yet');67	const TEAM = ['Amina Yusuf', 'Dilan Karim', 'Hevi Salih', 'Omar Nasir'];8	const STATUSES = ['Backlog', 'In progress', 'In review', 'Done'];910	const items: CommandGroup[] = [11		{12			heading: 'Issue',13			items: [14				{15					id: 'assign',16					label: 'Assign to…',17					placeholder: 'Who should take it?',18					children: TEAM.map((name) => ({19						id: `assign:${name}`,20						label: name,21						onselect: () => (ran = `Assigned to ${name}`)22					}))23				},24				{25					id: 'status',26					label: 'Change status…',27					children: STATUSES.map((status) => ({28						id: `status:${status}`,29						label: status,30						onselect: () => (ran = `Moved to ${status}`)31					}))32				}33			]34		},35		{36			heading: 'Preferences',37			items: [38				{39					id: 'theme',40					label: 'Theme…',41					children: [42						{43							heading: 'Appearance',44							items: [45								{ id: 'theme:light', label: 'Light', onselect: () => (ran = 'Light theme') },46								{ id: 'theme:dark', label: 'Dark', onselect: () => (ran = 'Dark theme') },47								{ id: 'theme:system', label: 'System', onselect: () => (ran = 'System theme') }48							]49						}50					]51				}52			]53		}54	];55</script>5657<div class="flex flex-col items-center gap-2">58	<Button variant="tonal" onclick={() => (open = true)}>Issue actions</Button>59	<Text variant="body-sm" tone="muted">Last run: {ran}</Text>60</div>6162<CommandPalette63	bind:open64	{items}65	hotkey={false}66	recentKey="omaris-docs-palette-recent"67	recent={3}68	placeholder="What do you want to do?"69/>

Server search

When a server does the searching: bind:query to send what is typed, filter={false} to show the answer exactly as it came back, and loading for the line under the field while it is on its way.

Picked: nobody yet

1<script lang="ts">2	import { Button, CommandPalette, Text, type CommandGroup } from 'omaris';34	const CUSTOMERS = [5		'Zagros Café',6		'Nishtiman Books',7		'Erbil Bakery',8		'Tigris Tailors',9		'Sulaymaniyah Print House',10		'Duhok Dairy',11		'Basra Marine Supply'12	];1314	let open = $state(false);15	let query = $state('');16	let loading = $state(false);17	let results = $state<CommandGroup[]>([]);18	let picked = $state('nobody yet');1920	/** Stands in for `fetch('/api/customers?q=…')`. */21	$effect(() => {22		const q = query.trim().toLowerCase();23		loading = true;24		const timer = setTimeout(() => {25			const items = CUSTOMERS.filter((name) => name.toLowerCase().includes(q)).map((name) => ({26				id: name,27				label: name,28				description: 'Customer',29				onselect: () => (picked = name)30			}));31			results = items.length ? [{ heading: 'Customers', items }] : [];32			loading = false;33		}, 400);34		return () => clearTimeout(timer);35	});36</script>3738<div class="flex flex-col items-center gap-2">39	<Button variant="outlined" onclick={() => (open = true)}>Find a customer</Button>40	<Text variant="body-sm" tone="muted">Picked: {picked}</Text>41</div>4243<CommandPalette44	bind:open45	bind:query46	items={results}47	filter={false}48	{loading}49	hotkey={false}50	placeholder="Search customers…"51/>

Overridden

class narrows the dialog, classes reaches the field, the rows and the highlight, footer replaces the key hints — here in Arabic, with every label translated and the page mirrored.

آخر أمر: —

1<script lang="ts">2	import { Button, CommandPalette, Text, type CommandGroup } from 'omaris';34	let open = $state(false);5	let ran = $state('—');67	const items: CommandGroup[] = [8		{9			heading: 'الطلبات',10			items: [11				{ id: 'ar-new', label: 'طلب جديد', shortcut: 'mod+n', onselect: () => (ran = 'طلب جديد') },12				{ id: 'ar-orders', label: 'كل الطلبات', onselect: () => (ran = 'كل الطلبات') }13			]14		},15		{16			heading: 'المظهر',17			items: [18				{19					id: 'ar-theme',20					label: 'تغيير المظهر',21					children: [22						{ id: 'ar-light', label: 'فاتح', onselect: () => (ran = 'فاتح') },23						{ id: 'ar-dark', label: 'داكن', onselect: () => (ran = 'داكن') }24					]25				}26			]27		}28	];29</script>3031<div dir="rtl" lang="ar" class="flex flex-col items-center gap-2">32	<Button variant="outlined" onclick={() => (open = true)}>لوحة الأوامر</Button>33	<Text variant="body-sm" tone="muted">آخر أمر: {ran}</Text>3435	<CommandPalette36		bind:open37		{items}38		dir="rtl"39		lang="ar"40		hotkey={false}41		label="لوحة الأوامر"42		placeholder="اكتب أمرًا أو ابحث…"43		backLabel="رجوع"44		clearLabel="مسح"45		class="max-w-lg"46		classes={{47			header: 'bg-surface-container-low',48			option: 'rounded-full',49			highlight: 'text-tertiary underline decoration-2 underline-offset-4'50		}}51	>52		{#snippet empty(query)}53			<Text variant="body-md" tone="muted">لا نتائج لـ «{query}»</Text>54		{/snippet}55		{#snippet footer()}56			<Text as="span" variant="label-sm">↑↓ للتنقل · ↵ للاختيار · esc للإغلاق</Text>57		{/snippet}58	</CommandPalette>59</div>

When to use it

Use it for

One place to reach everything in an app from the keyboard — pages, actions, records — opened with ⌘K (hotkey, mod+k by default) from anywhere.
Actions that take a second choice: "Assign to…", "Move to…", "Theme…" as a row with children, which opens as its own page.
Searching records on a server: bind:query to send what is typed, filter={false} to show the answer as it came back, loading meanwhile.
The rows people use most, first: recentKey remembers the last recent choices across visits.

Not for

Filtering a list that is already on the screen → Search Bar. The palette covers the page; a filter should leave the results in view.
Picking a value for a form field → Combobox.
The actions of one row or one button → Menu.
The app's primary navigation → Navigation Drawer or Navigation Bar. A palette is a shortcut to places, not the only way there — nothing on a phone has ⌘K.

Do

Give every row a stable, unique id; it keys the list and it is what recent stores.
Add keywords for the words people will actually type — "preferences" and "account" for Settings.
Start a label with the verb or the place: "New issue", "Go to billing". The first letters rank highest.
Keep a visible way to open it — a button with a Kbd in it, or a search field in the top bar — for touch screens and for people who do not know the shortcut.
Put the shortcut on a row only when that shortcut really works outside the palette; the cap is a promise.

Don't

Register ⌘K twice. If the app already binds it (a docs search, a browser extension you ship), pass another hotkey or false.
Put a form in a page. A page is a list to choose from; a form belongs in a Dialog the chosen row opens.
Announce what a row did with a toast when its result is on screen — the page navigated, the theme changed.
Nest pages more than two deep. Past that, people lose the thread even with the chips.

Pairs with Kbd Dialog Top App Bar Search Bar Button

API

CommandPalette

⌘K — a search field over every action in the app, opened from anywhere.

Built on Dialog, so it gets the focus trap, the inert page behind and Escape for free, and on a phone it is the same bottom sheet every dialog becomes there — stretched to full height, with the field at the top where the thumb and the keyboard both expect it.

Matching is fuzzy, and ranked the way people type: gs finds "Go to settings", nwis finds "New issue", and the characters that matched are drawn in the accent colour. Results keep their groups, best group first.

An item with children is a page: selecting it opens those as a new list with its name as a chip in the field, Backspace on an empty field goes back, and a search from the top level reaches into every page at once.

The field is a real combobox over a real listbox: ↑ and ↓ move (and wrap), Enter runs, aria-activedescendant keeps a screen reader on the active row, and the active row scrolls itself into view. The global hotkey (mod+k by default) is listened for only while the palette is mounted.

import { CommandPalette } from 'omaris'

<CommandPalette  bind:open  items={[    { heading: 'Go to', items: [{ id: 'inbox', label: 'Inbox', href: '/inbox', shortcut: 'mod+i' }] },    { heading: 'Actions', items: [{ id: 'new', label: 'New issue', shortcut: 'c', onselect: create }] }  ]}/>

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: The Dialog itself.
body: The dialog's body — what the palette's height is measured from.
header: The search row: icon or back button, page chips, field.
searchIcon: The magnifier at the start of the field.
back: The back button, in the magnifier's place on a nested page.
crumbs: The chips naming each page opened on the way here.
crumb: One page chip — a Chip, so this lands on its root.
input: No description in the source yet.
clear: The × that empties the field.
progress: The line under the field while loading.
list: The scrolling listbox.
page: The results of one page, faded in as the page changes.
group: One group of results.
heading: No description in the source yet.
option: No description in the source yet.
icon: The icon well at the start of a row.
text: Label and description, stacked.
label: No description in the source yet.
path: "Theme ›" before a result found inside a page.
description: No description in the source yet.
highlight: The characters that matched the query.
shortcut: The row's shortcut — hidden on touch, where there is no keyboard.
chevron: The › on a row that opens a page.
empty: No description in the source yet.
footer: The key hints along the bottom. Hidden on touch.
hint: No description in the source yet.

Props

open bindable

Defaults to false

boolean

Bindable.

items required

CommandGroup[]

The rows, in groups.

query bindable

Defaults to ''

string

What is typed in the field. Bindable, for searching a server as it changes.

placeholder

Defaults to 'Type a command or search…'

string

hotkey

Defaults to 'mod+k'

string | string[] | false

The shortcut that toggles it from anywhere on the page — 'mod+k' is ⌘K on a Mac and Ctrl+K elsewhere. false for none. Listened for only while the palette is mounted.

recent

Defaults to 5

number

How many recently chosen rows to remember and show first. Needs recentKey.

recentKey

string

localStorage key the recent rows are kept under. Without one, nothing is remembered.

recentHeading

Defaults to 'Recent'

string

Heading over the recent rows.

loading

Defaults to false

boolean

Draw a progress line under the field — for results that are on their way.

empty

Snippet<[string]>

Drawn when nothing matches. Handed the query.

filter

CommandFilter | false

Replace the fuzzy ranking. false shows items exactly as given, for a list a server has already filtered.

limit

Defaults to 100

number

Most results shown for a query. The best ones, by score.

onselect

(item: CommandItem) => void

Called with every row chosen, after the row's own onselect.

closeOnSelect

Defaults to true

boolean

Close once a row has been chosen. On by default.

label

Defaults to 'Command palette'

string

Accessible name of the dialog.

backLabel

Defaults to 'Back'

string

Accessible name of the back button on a nested page.

clearLabel

Defaults to 'Clear'

string

Accessible name of the button that empties the field.

hints

Defaults to true

boolean

The key hints along the bottom. Hidden on touch either way.

footer

Snippet

Replaces the key hints — in another language, say. Hidden on touch too.

mobileQuery

Defaults to '(max-width: 639px)'

string

What counts as a phone — below it the palette is a full-height sheet.

onclose

() => void

Called after it has finished closing.

class

string

classes

CommandPaletteClasses

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