<kern-command-palette>
Search field over pages, devices and actions in a modal (kern-dialog), to reach them by keyboard: «Boiler», «Updates», «Start scan». Open it with a button calling show(), by setting open, or with Ctrl+K / Cmd+K when shortcut is set.
Choosing an entry closes the palette and reports its id in kernSelect; navigating, permissions and running the action stay with the app (dangerous actions go through its confirmation, e.g. confirm()). Disabled entries are shown but cannot be chosen.
By default the palette searches items itself: every word must occur in the label, a keyword or the group (case and diacritics ignored); label matches rank first and are highlighted. With filtering="external" it shows items as given: load results on kernQueryChange and set items, loading and error. Ignore answers to older queries yourself (see the example), so a slow response cannot overwrite newer results.
Keyboard: Arrow Up/Down, Home and End move the active entry, Enter chooses it, Escape (or a click on the backdrop) closes. The focus is in the search field while open and returns to where it was (the button, a field) on close. The number of results is announced politely once typing pauses («5 results»).
shortcut registers one keydown listener on the document, removed with the last palette that uses it. Enable it on one palette per page; with several, the open one closes and otherwise the last connected one opens. It does not open while a modal dialog is open (kern-dialog, kern-drawer or a native one, also inside shadow roots), and ignores keys an app handler already took (preventDefault).
Examples
Local search
Give the palette all items and it searches them itself: every word must occur in the label, a keyword or the group (case and diacritics ignored, so «kuche» finds «Küche Licht»). Label matches rank first and are highlighted; keywords make an IP, a MAC or a synonym findable without showing it. Groups appear in the order of their first entry.
Open it with a button calling show(), or with Ctrl+K / Cmd+K: shortcut is off by default, so enable it on one palette per page. Arrow keys, Home and End move the active entry (disabled ones are skipped), Enter or a click chooses, Escape or a click on the backdrop closes, and the focus returns to where it was.
kernSelect reports only the id; the palette is already closed. Navigating, permissions and running the action are up to your app, and dangerous actions go through its usual confirmation, here confirm().
Server search
With filtering="external" the palette shows items as given and leaves the search to your server: load results on kernQueryChange (also fired with '' when closing clears the search) and set items, loading and error. While loading, a spinner shows in the search field and the previous results stay; without any, «Searching …» appears. error replaces the results with an error state, and no results show «No results». The count is announced politely once typing and loading pause.
Answers can arrive out of order: the reply to «bo» may come after the one to «boiler». Ignoring stale answers is up to your app; the palette shows whatever you set last. Here a request counter drops every answer that is not for the latest query; an AbortController per query works as well and also saves the server work. Debounce kernQueryChange if your server needs it.
The example uses a fake server with 300–550 ms delay. «Fail next search» makes the next request fail.
Properties
errorstring | undefined
Message of a failed search; shown instead of the results.
filtering"external" | "local"
local: the palette filters and ranks items. external: items are the results for query from your server.
itemsKernCommandItem[]
Entries: { id, label, description?, group?, icon?, keywords?, disabled? }. Groups appear in the order of their first entry.
labelstring | undefined
Accessible name of the dialog and the search field.
labelLoadingstring | undefined
Shown while loading without results.
labelNoResultsstring | undefined
Heading when nothing matches.
labelOneResultstring | undefined
Announced for exactly one result.
labelResultsstring | undefined
Announced number of results; {n} is replaced.
loadingboolean
Results are loading: a spinner in the search field, and «Searching …» while there is nothing to show.
openboolean
Whether the palette is open.
placeholderstring | undefined
Placeholder of the search field.
querystring
The search text; changes while typing and is cleared when the palette closes.
shortcutboolean
Ctrl+K / Cmd+K (with shortcut-key) opens and closes the palette from anywhere in the page.
shortcutKeystring
Key pressed with Ctrl or Cmd for shortcut.
Events
kernCloseCustomEvent<void>
After the palette closed.
kernOpenCustomEvent<void>
After the palette opened; the focus is in the search field.
kernQueryChangeCustomEvent<{ query: string; }>
On every change of the search text by typing, and with '' when closing clears it. Load results here (filtering="external").
kernSelectCustomEvent<{ id: string; }>
An enabled entry was chosen (Enter or click); the palette is already closed.
Methods
hide()hide() => Promise<void>
Closes the palette; the focus returns to where it was before opening.
show()show() => Promise<void>
Opens the palette; the focus moves to the search field.
CSS parts
optionEach entry