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
| Keys | Does |
|---|---|
| Ctrl+K Ctrl+Shift+P | Open or close (the toggle shortcuts of this app) |
| ↑ ↓, Ctrl N / P, Ctrl J / K | Move, wrapping around at either end unless Loop is off (J/K with VimBindings) |
| Home End PgUp PgDn | Jump to the first, the last, or ten rows on |
| Enter | Run, 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 Enter | Apply a multi-select page, run the row's first secondary action, or open a link in a new tab |
| Tab, → (empty box), a right click | Open the action panel of the active row |
| Backspace, ← (empty box) | Back one page |
| Esc | Cancel a confirmation, then go back, then close |
| Ctrl Shift P | Pin or unpin the active row - inside the palette its own chord wins over this app's toggle on the same keys |
| Shift Del | Forget 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.
| Shortcut | Command | Group | Kind |
|---|---|---|---|
| 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 |
@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
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, orkeyCode229) 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 keyConflicts
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…).
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
| Option | Here | Effect |
|---|---|---|
ToggleShortcut | mod+k | Opens and closes the palette; Mod is ⌘ on macOS and Ctrl elsewhere. The palette's ToggleShortcut parameter overrides it. |
AdditionalToggleShortcuts | mod+shift+p | More keys for the same. |
SequenceTimeoutMs | 1000 | How long G waits for the next key. |
ShowSequenceHint | True | The status that shows a sequence in progress. |
SuppressShortcutsInEditableElements | True | Plain keys in inputs are typing, as above. |
Loop | True | Past the last row comes the first again. |
VimBindings | True | Ctrl 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
comboboxcontrolling alistbox;aria-activedescendantpoints at the activeoption, which carriesaria-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'saria-expandedfollows. On a prompt the input is a plain text field named by the prompt's question. In a virtualized list each option carriesaria-posinsetandaria-setsize. - A multi-select page adds
aria-multiselectableand marks its checked optionsaria-checkedand 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-busywhile it loads. - A toggle's state and a pinned command are spoken ("On", "Off", "Pinned"), not only drawn; disabled commands are
aria-disabledand 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;
DisablePointerSelectionturns 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.