On this page
@addTagHelper *, Webority.Ui.RazorSearch and jump
Group results under headings, and let the page own the search so the palette only draws what it is given.
Nested pages
Use a page for an item that opens a group of results, and the path records where the user is.
Recent items
Remember what a person chose on this device, so the list starts with what they used last.
Shortcut hints
Draw an item's shortcut as a key chip, as a hint only, because the page binds the key itself.
Opening it
Open the palette with Ctrl or Cmd+K anywhere, and offer a visible button for anyone who does not know it.
Keyboard and pointer
Focus stays in the input the whole time. ArrowDown and ArrowUp move the highlighted result across every group and wrap at both ends; the highlighted result scrolls into view. Enter opens it. Hovering a result highlights it. Escape or a click on the dimmed page closes the palette, and focus goes back to where it was.
Every option
Every value of every prop, one cell each.
open
open (React only; Razor opens with data-bs-toggle)
onClose
onClose (React only; Razor closes on Escape or a click on the dimmed page)
query
query (React only; Razor filters the items it drew)
onQueryChange
onQueryChange (React only; Razor filters in the page)
groups
icon, description and meta
shortcut (a key chip)
page (a chevron)
label only
groups={[]} (default, React; Razor: no app-command-group)
path
path (React only; Razor uses page on an item)
onPathChange
onPathChange (React only; Razor opens a page with page on an item)
rootLabel
root-label (default, "All")
root-label="Everything"
backLabel
back-label (default, "Back")
back-label="Previous"
recentsKey
recents-key (default, none: no recents)
recents-key="sandbox:command-palette:every-option"
recentsLimit
recents-limit (default, 5)
recents-limit="2"
recentsLabel
recents-label (default, "Recent")
recents-label="Last used"
placeholder
placeholder (default, "Search…")
placeholder="Find a page or action"
loading
loading (React only; Razor draws its list on the server, so no spinner)
emptyText
empty-text (default, "No results")
empty-text="Nothing matches that"
footer
footer (Razor: an app-command-palette-footer child)
ariaLabel
aria-label (default, "Search")
aria-label="Find a page"
highlight
highlight (default, true)
highlight="false"
groupFilter
group-filter (default, false)
group-filter (a pill per group)
resultsLabel
results-label (names the results list for screen readers)
id
id (seeds the result and heading ids)
className
class (React: className; extra classes on the dialog card)
shortcut-key
shortcut-key="k" (React: useCommandPaletteShortcut)
Guidance
What to do, and what to avoid.
Use it when
- An app has more pages and actions than its navigation can show at once.
- Regular users want to jump straight to a record or run an action from the keyboard.
- The same search should reach pages, actions and records in one place.
Reach for something else when
- You are picking a value for a form field. → AppSelect mode="search"
- You are filtering the list on the current page. → AppSearch
- The palette would be the only way to reach a page. → AppShell
Reference
Try every prop, read the full list, and check keyboard and screen reader behaviour.
14 props. The 1 most used come first.
Used on most screens 1 props
| Prop | Type | Default | Description |
|---|---|---|---|
| placeholderdefault Search… | string | Search… | The text the search field shows while it is empty. |
Less common 13 props
| Prop | Type | Default | Description |
|---|---|---|---|
| iddefault - | string | - | Seeds the result and heading ids; defaults to a generated id. |
| empty-textdefault No results | string | No results | Shown when the typed search matches no item. |
| aria-labeldefault Search | string | Search | Accessible name of the dialog and its input. |
| highlightdefault true | bool | true | Bold the query inside each string label, case-insensitively. A label given as a node renders as it is. |
| group-filterdefault false | bool | false | Adds a tab per group above the results, so a person narrows to one group. |
| root-labeldefault All | string | All | Breadcrumb text for the first page. |
| results-labeldefault Results | string | Results | Replaces the built-in English text, for other languages. |
| back-labeldefault Back | string | Back | Accessible name of the Back button. |
| recents-keydefault - | string | - | localStorage key to remember chosen items under; omit for no recents. Make it per user, for example from the user's public id. |
| recents-limitdefault 5 | int | 5 | How many recent items to keep (at most 20). |
| recents-labeldefault Recent | string | Recent | Heading of the recent items. |
| shortcut-keydefault - | string | - | The key that, with Ctrl or Cmd, opens the palette. |
| classdefault - | string | - | Extra classes on the modal shell, as on <app-modal>. |
1 props.
Less common 1 props
| Prop | Type | Default | Description |
|---|---|---|---|
| keywordsdefault - | string | - | Other words the item answers to, such as synonyms, separated by spaces. The search matches them the way it matches the label. |
Screen reader
3 notes- The search field is a combobox that names the listbox it controls, and the dialog and the field take the ariaLabel prop as their accessible name.
- Results sit in a listbox in groups named by their headings; each option's accessible name is its ariaLabel or its string label, and a disabled item is marked aria-disabled.
- Escape and a click on the dimmed page close the palette, and focus returns to where it was before it opened, because the dialog is AppModal.