Skip to content

Keyboard & shortcuts

The palette is built to be driven without a mouse. Inside it every key has a job; outside it, any command can carry a global shortcut - a chord such as Ctrl / or a sequence such as G then S - that runs it with the palette closed. Shortcuts are written once, as text, and displayed in the platform's own symbols.

Inside the palette

KeysDoes
Ctrl+K Ctrl+Shift+P Open or close (the toggle shortcuts of this app)
↑ ↓, Ctrl N / P, Ctrl J / KMove, wrapping around at either end unless Loop is off (J/K with VimBindings)
Home End PgUp PgDnJump to the first, the last, or ten rows on
EnterRun, open a page, flip a toggle, check a row on a multi-select page, or arm and then confirm a destructive command
Space (empty box)Check a row on a multi-select page
Ctrl EnterApply a multi-select page, run the row's first secondary action, or open a link in a new tab
Tab, → (empty box), a right clickOpen the action panel of the active row
Backspace, ← (empty box)Back one page
EscCancel a confirmation, then go back, then close
Ctrl Shift PPin or unpin the active row - inside the palette its own chord wins over this app's toggle on the same keys
Shift DelForget the active row from the recents

These keys are claimed in the browser before Blazor sees them, so Tab never leaves the dialog and Backspace never deletes text it should not, even over a slow Blazor Server connection. In right-to-left text ← and → trade places: → points back to the start of the line, so it goes back a page. Inside the palette its own chords also win over a toggle bound to the same keys: with this app's Vim bindings, Ctrl K moves up rather than closing.

Global shortcuts in this app

Every command registered with a global shortcut, read from the registry right now - leave a page and its own shortcuts disappear from this table, because they disappear from the palette. Close the palette and press one; press G on its own and the status below - and the one at the bottom of the window - waits for the next key.

The registry's shortcuts
ShortcutCommandGroupKind
F2 Rename project… Actions chord
Ctrl+Shift+C Copy share link Actions chord
Ctrl+/ Keyboard shortcuts Help chord
Alt+Z Word wrap Preferences chord
Alt+Q Save draft This page chord
G then H Introduction Navigation sequence
G then I Quick start Navigation sequence
G then R Registering commands Navigation sequence
G then S Settings Navigation sequence
G then P Nested pages and flows Navigation sequence
G then F Search and ranking Navigation sequence
G then M Modes and sources Navigation sequence
G then K Keyboard and shortcuts Navigation sequence
G then T Theming and templates Navigation sequence
G then L Large registry Navigation sequence
G then O Options and security Navigation sequence
G then A MCP server Navigation sequence
C New issue Quick create chord, declared in markup
Last run: nothing yet Sequence: none in progress
@inject IBaletteService Palette
@implements IDisposable

@foreach (var command in Palette.Commands.Where(c => c.Shortcut is not null && c.GlobalShortcut))
{
    <tr>
        <td><BaletteShortcutHint Shortcut="command.Shortcut" IsMac="Palette.IsMac" /></td>
        <td>@command.Title</td>
        <td>@(command.Shortcut!.IsSequence ? "sequence" : "chord")</td>
    </tr>
}

@code {
    // A page's commands come and go with the page: list the registry again when it changes.
    protected override void OnInitialized() => Palette.CommandsChanged += Refresh;

    private void Refresh() => _ = InvokeAsync(StateHasChanged);

    // The service outlives the page: a handler left on it keeps the page alive and rendering.
    public void Dispose() => Palette.CommandsChanged -= Refresh;
}

The registered shortcuts are synced to the browser as strings and matched there, so only a completed shortcut crosses the interop boundary - typing on the page never causes a round trip. A sequence waits SequenceTimeoutMs (1000 ms) for its next chord. Whatever needs the palette opens it: a command with a page or a confirmation, and a handler that answers with a page, a prompt or a toast that stays open - F2 opens on the rename prompt. A confirmation started this way gets a page of its own, so the second Enter confirms that command and no other. Only a command that can run claims its keys: the shortcut of a disabled command, or of one its VisibleWhen hides, is left to the page.

Sequences in progress

After the first chords of a sequence - G of G S - a small status near the bottom of the page shows them and says the next key is awaited, as VS Code does in its status bar, and screen readers announce it (data-balette="sequence", BaletteStrings.SequencePending). It goes when the sequence completes, breaks off or times out. options.ShowSequenceHint = false turns it off; IBaletteService.SequencePending reports it to code either way - with the chords pressed so far, then null - which is what the status line above listens to:

Palette.SequencePending += pending =>
{
    // "G" after the first key of G S, null once it completed, broke off or timed out.
    _pending = pending;
    InvokeAsync(StateHasChanged);
};

Typing is not a shortcut

A plain key pressed in a text box is typing, so G then S does nothing here. A chord with a modifier still works - Ctrl K opens the palette and Alt Z flips word wrap - because nobody types those by accident. Inputs, text areas, selects and content-editable elements all count (SuppressShortcutsInEditableElements).

builder.Services.AddBitBaletteServices(options =>
{
    // On by default: a plain key pressed in a text field is typing. Off, G then S fires there too.
    options.SuppressShortcutsInEditableElements = false;
});

BaletteCmd.New("Search").Shortcut("/")          // a plain key: never while typing, unless turned off
BaletteCmd.New("Word wrap").Shortcut("Alt+Z")   // a chord with a modifier: anywhere
This site has a second palette: the documentation search in its header, which answers to / because Ctrl K is Balette's. Whichever of the two is open owns the keyboard - a chord pressed in the docs search does not open Balette on top of it, and a / pressed in Balette does not open the search.

Keyboard layouts, held keys and input methods

  • A shortcut is matched on the character the key types and, when that is not an ASCII character, on the key it sits on as well (KeyboardEvent.code, as VS Code does): Ctrl K works when a Russian layout types л, and G S when a Persian one types ل س. A Latin layout such as Dvorak or AZERTY keeps its own letters.
  • A held key's repeats are claimed - the browser does not act on them - but run nothing, so a held Ctrl K does not flicker the palette open and shut.
  • A character typed with AltGr, or with Option or Alt alone (Ω for Option+Z on a Mac), is typing when it lands in a text field, not the shortcut its physical key would make.
  • Keys that belong to an input method's composition (isComposing, or keyCode 229) are never shortcuts, so confirming a Japanese or Chinese candidate with Enter does not run the active row.

Shortcut syntax

Chords are separated by spaces and keys inside a chord by +. Mod is ⌘ on macOS and Ctrl elsewhere. Modifiers have aliases (Control, Cmd, Command, Win, Option, Opt, ⌃, ⇧, ⌥, ⌘), and so do keys (Esc, Return, Space, Del, Up, PgDn, Plus, Comma, Slash…). BaletteKeyboardShortcut.Parse throws a FormatException for a chord without a key or with two; TryParse does not, and a string converts implicitly wherever a shortcut is expected. Type one:

On macOS
⌘⇧K
Elsewhere
Ctrl+Shift+K
In words
Ctrl+Shift+K
Normalized
mod+shift+k
Kind
a chord
BaletteCmd.New("Copy share link").Shortcut("Mod+Shift+C")      // a chord: ⌘⇧C or Ctrl+Shift+C
BaletteCmd.Navigate("Settings", "/settings").Shortcut("G S")    // a sequence: G, then S
BaletteCmd.New("Search").Shortcut("/", global: true)            // a single key; ignored while typing in a field
BaletteCmd.New("Find in page").Shortcut("Mod+F", global: false) // shown as a hint only

options.ToggleShortcut = "Mod+K";                               // the default
options.AdditionalToggleShortcuts.Add("Mod+Shift+P");

BaletteKeyboardShortcut shortcut = "Ctrl+Shift+P";              // a string converts implicitly
bool ok = BaletteKeyboardShortcut.TryParse("Ctrl+Shift", out _);   // false: no key

Conflicts

When several commands claim one global shortcut, the one registered last wins - the rule ids follow too - so a page's own Ctrl S takes over from the layout's while the page is shown. The palette logs a warning, once each, for:

  • a shortcut several commands claim;
  • one the toggle shortcut takes, so the command never runs from it;
  • a sequence that can never complete because its first chords are a shortcut of their own - G registered next to G I;
  • one browsers keep for themselves and never hand to a page (Ctrl W, Ctrl T, Ctrl N, Ctrl Tab…).
Two commands, one shortcut

This page registers Save draft on Alt Q. Register Save and publish on the same keys and, with the palette closed, Alt Q runs it instead - the later registration wins - while the browser's console shows the palette's warning naming both. Dispose it and the keys are Save draft's again.

Alt Q runs Save draft · Last pressed: not yet

// The page's own command on Alt+Q, registered by <BaletteCommands Commands="_pageCommands" /> while the page is shown...
_pageCommands = [BaletteCmd.New("Save draft").Group("This page").Shortcut("Alt+Q").Handler(SaveDraft)];

// ... and a second one on the same keys: registered later, so it wins them, and the palette logs a warning.
_override = Palette.Register(BaletteCmd.New("Save and publish").Group("This page").Shortcut("Alt+Q").Handler(Publish));

// Disposed, and Alt+Q is Save draft's again.
_override.Dispose();

Platform-aware hints

The palette detects macOS and iOS once it starts, and every hint follows: ⌘ ⇧ K there, Ctrl Shift K elsewhere. IBaletteService.IsMac exposes the result to your own UI - this browser is not a Mac - and PlatformDetected says when it is known. BaletteShortcutHint renders any shortcut the same way the palette does, with an accessible name in words ("Ctrl+K", "G then S") while its key caps are hidden from screen readers, and BaletteTrigger updates itself. Every hint on this page is one.

@inject IBaletteService Palette
@implements IDisposable

<BaletteShortcutHint Shortcut="command.Shortcut" IsMac="Palette.IsMac" />

@code {
    // IsMac is known once the palette has started in the browser.
    protected override void OnInitialized() => Palette.PlatformDetected += Refresh;

    private void Refresh() => _ = InvokeAsync(StateHasChanged);

    public void Dispose() => Palette.PlatformDetected -= Refresh;
}

The options behind it

OptionHereEffect
ToggleShortcutmod+kOpens and closes the palette; Mod is ⌘ on macOS and Ctrl elsewhere. The palette's ToggleShortcut parameter overrides it.
AdditionalToggleShortcutsmod+shift+pMore keys for the same.
SequenceTimeoutMs1000How long G waits for the next key.
ShowSequenceHintTrueThe status that shows a sequence in progress.
SuppressShortcutsInEditableElementsTruePlain keys in inputs are typing, as above.
LoopTruePast the last row comes the first again.
VimBindingsTrueCtrl J / K move inside the list.

Loop and VimBindings can also be set on one palette, with the parameters of the same names.

builder.Services.AddBitBaletteServices(options =>
{
    options.ToggleShortcut = "Mod+K";                 // null for none
    options.AdditionalToggleShortcuts.Add("Mod+Shift+P");
    options.SequenceTimeoutMs = 1500;                 // how long G waits for the next key
    options.ShowSequenceHint = false;                 // no status while a sequence is in progress
    options.Loop = false;                             // stop at the first and the last row
    options.VimBindings = true;                       // Ctrl+J / Ctrl+K move inside the list
});
<Balette Loop="false" VimBindings="true" ToggleShortcut="Mod+P" />

Accessibility

  • A native modal <dialog>: it sits in the top layer, traps focus, makes the page behind it inert, locks scrolling, and gives focus back to whatever had it when it closes.
  • The WAI-ARIA combobox pattern: focus stays on the input, a combobox controlling a listbox; aria-activedescendant points at the active option, which carries aria-selected, so screen readers follow the selection without focus moving.
  • Each group is a role="group" named by its heading (the grouped listbox), so screen readers say which group an option is in. The list is a listbox only while it lists something - the empty, loading and error states are statuses and alerts instead - and the combobox's aria-expanded follows. On a prompt the input is a plain text field named by the prompt's question. In a virtualized list each option carries aria-posinset and aria-setsize.
  • A multi-select page adds aria-multiselectable and marks its checked options aria-checked and nothing else - one state per list, as the pattern asks.
  • Polite live regions, present before anything is announced in them, say the result count after every search, the page the palette moved to ("Theme. 3 results available"), loading, and every toast; errors are announced assertively. The list is aria-busy while it loads.
  • A toggle's state and a pinned command are spoken ("On", "Off", "Pinned"), not only drawn; disabled commands are aria-disabled and say why; group headings are presentational, so they are not read as options.
  • Shortcut hints have an accessible name in words, and the trigger declares aria-keyshortcuts. The close button's accessible name holds its visible "Esc" (WCAG 2.5.3), and the buttons are at least 24 px.
  • Mouse hover moves the active row only after the pointer actually moves, so a list that scrolls under a resting pointer does not steal the selection from the keyboard; DisablePointerSelection turns hover off completely. Clicking a row leaves the focus in the input.
  • More contrast, forced colours, reduced motion and right-to-left layouts are styled for - see Theming and Localization.
The browser suite runs axe-core (WCAG 2.2 A and AA rules) over the root list, search results, a nested page, a multi-select page and a prompt, in light and dark, with this site's theme and with the library's defaults, and reads Chromium's accessibility tree directly. An automated audit finds only part of the problems; it is not a claim of conformance, and screen reader testing by people who use them remains the measure.
An unhandled error has occurred. Reload 🗙