Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Search and jump

Group results under headings, and let the page own the search so the palette only draws what it is given.

Pages, actions and people
Typing narrows the list and bolds the matching text in each label.
Show code
<app-command-palette id="jump" shortcut-key="k">
    <app-command-group label="Pages">
        <app-command-item label="Dashboard" href="/" icon="house" meta="G D" />
        <app-command-item label="Projects" href="/projects" icon="folder" description="Every project you can see" />
    </app-command-group>
    <app-command-group label="Actions">
        <app-command-item label="New project" href="/projects/new" icon="plus" />
    </app-command-group>
</app-command-palette>

Nested pages

Use a page for an item that opens a group of results, and the path records where the user is.

Pages that open pages
Projects opens Archived, with breadcrumbs and a Back button.
Show code
<app-command-palette id="jump" root-label="All">
    <app-command-group label="Go to">
        <app-command-item label="Projects" page="projects" icon="folder" />
    </app-command-group>
    <app-command-page key="projects" label="Projects">
        <app-command-group label="Projects">
            <app-command-item label="Alpha" href="/projects/alpha" />
        </app-command-group>
    </app-command-page>
</app-command-palette>

Recent items

Remember what a person chose on this device, so the list starts with what they used last.

Remembered per device
Items chosen earlier appear under Recent after the palette closes and reopens.
Show code
<app-command-palette id="jump" recents-key="command-palette:@user.PublicId" recents-limit="5">
    …
</app-command-palette>

Shortcut hints

Draw an item's shortcut as a key chip, as a hint only, because the page binds the key itself.

Item shortcuts
Two actions show a key chip at the end of their rows.
Show code
<app-command-item label="New project" href="/projects/new" icon="plus" shortcut="N" />

Opening it

Open the palette with Ctrl or Cmd+K anywhere, and offer a visible button for anyone who does not know it.

Ctrl+K with key hints
The shortcut opens the palette, and its footer lists key hints.
Show code
<script>
    document.addEventListener('keydown', function (e) {
        if ((e.ctrlKey || e.metaKey) && !e.altKey && !e.shiftKey && !e.repeat && e.key.toLowerCase() === 'k') {
            e.preventDefault();
            WUI.modal.open('jump');
        }
    });
</script>

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.

Move with the arrow keys
The input is a combobox that points at the listbox and at the highlighted result, so each arrow press is announced. Each group is labelled by its heading. The empty text sits in a status region, so it is read out when it appears.
Show code
<app-command-palette id="jump">
    <app-command-group label="Pages">
        <app-command-item label="Dashboard" href="/" icon="house" />
    </app-command-group>
</app-command-palette>

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.

React, generated from the controls
<AppCommandPalette
  open={open}
  id="pgPalette"
  onClose={() => setOpen(false)}
  query={query}
  onQueryChange={setQuery}
  groups={results}
  footer={hints}
/>
Razor, the same props
<app-command-palette id="pgPalette">…</app-command-palette>

14 props. The 1 most used come first.

Used on most screens 1 props

PropTypeDefaultDescription
placeholderdefault Search… string Search… The text the search field shows while it is empty.

Less common 13 props

PropTypeDefaultDescription
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

PropTypeDefaultDescription
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.