Skip to content

Options & security

Every option of BaletteOptions, with the value this site runs with next to the library's default; the parameters that override them for one palette; the component's own methods and callbacks; and what the palette does to keep text, links and history safe.

Search the options

An inline palette over the table below, driven through the component itself rather than the service: a @ref to call SetQueryAsync, OnQueryChanged and OnCommandExecuted to follow it, and a DetailTemplate for the active option. Choosing an option scrolls to its row.

ToggleShortcutOpens and closes the palette; null for none. The palette's ToggleShortcut parameter overrides it. mod+k
AdditionalToggleShortcutsMore shortcuts that do the same. mod+shift+p
SuppressShortcutsInEditableElementsPlain keys pressed in an input, a text area or a content-editable element are typing, not shortcuts; chords with a modifier still fire. true
SequenceTimeoutMsHow long a sequence (G I) waits for its next chord. Must be positive. 1000
ShowSequenceHintShows and announces a sequence in progress. true
LoopArrowing past the last row comes back to the first. true
VimBindingsCtrl+J / Ctrl+K move inside the list; Ctrl+N / Ctrl+P always do. true
DebounceMsQuiet time after the last keystroke before async sources are asked. Must not be negative. 150
SourceTimeoutMsHow long a source may take before it counts as failed and gets a retry row; 0 waits for ever. 10000
SourcesAsync sources asked in the default mode. Documentation
ModesModes registered at startup. > # @ ?
ShowModeHintsThe Modes group on the empty query. true
CommandsCommands registered at startup. none
GroupOrderGroups listed first on the empty query, in this order; the rest follow. Navigation, Actions, Preferences, Danger zone, Help
GroupWhenSearchingResults keep their group headings while searching; false lists one flat ranked list. true
MaxResultsRows kept per query, groups excluded; pinned and recent commands are listed beyond it. Must be positive. 150
MatcherScores and highlights every field: fuzzy by default, BaletteSubstringMatcher or your own. BaletteFuzzyMatcher
WeightsField weights: title, keywords, subtitle, group, path, description, tags. 1 / 0.9 / 0.7 / 0.5 / 0.5 / 0.4 / 0.3
PriorityWeightHow much a command's priority nudges its rank while searching. 0.25
FrecencyWeightHow much frecency - use, weighted by how recent - nudges it. 6
SearchNestedCommandsNested commands are found from the root page, with their path. true
TypoToleranceA query that found nothing is retried allowing a typo per term. true
HighlightMatchesMatched characters in titles and subtitles are marked. true
EnableHistoryRecords recents, pins and frecency. true
MaxRecentsRecent commands listed on the empty query. 5
MaxHistoryEntriesCommands the history keeps at most; pinned ones are never pruned. 200
HistoryStorageKeyThe localStorage key of the default history store. bit-balette.history
CloseOnBackdropClickA click on the backdrop closes the palette. true
CloseOnNavigationThe palette closes when the app navigates. true
ResetOnCloseClosing clears the query and the pages; false reopens where it was left. true
ShowFooterThe hint bar under the list, where toasts show. true
ShowShortcutsShortcut hints at the end of the rows. true
VirtualizeRenders only the visible rows; recommended above about 500. false
RowHeightA row's height in pixels while virtualized. Must be positive. 44
Densitycomfortable or compact; exposed as data-density. comfortable
Themeauto follows the page; light or dark forces one. auto
StringsEvery label and announcement. BaletteStrings
AllowedUrlSchemesSchemes an Href may use; relative links always may. http, https, mailto, tel
RecordCommandIdsInTracesWhether balette.command activities carry the command's id; metrics never do. true

OnQueryChanged: (empty) · OnCommandExecuted: nothing yet

<button @onclick='() => _finder.SetQueryAsync("history")'>SetQueryAsync("history")</button>

<Balette @ref="_finder"
         Inline="true"
         IncludeRegisteredCommands="false"
         Commands="_optionCommands"
         OnQueryChanged="query => _finderQuery = query"
         OnCommandExecuted="e => _finderLast = e.Command.Title">
    <DetailTemplate>
        <h3>@context.Title</h3>
        <p>@context.Subtitle</p>
    </DetailTemplate>
</Balette>

@code {
    private Balette _finder = default!;
    private string _finderQuery = "";
    private string? _finderLast;
}

Every option

Set in AddBitBaletteServices(options => ...). The options are a singleton; numbers that must be positive or not negative throw an ArgumentOutOfRangeException when set otherwise. Rows this site changed are marked.

builder.Services.AddBitBaletteServices(options =>
{
    options.MaxResults = 100;        // must be positive: 0 throws ArgumentOutOfRangeException
    options.DebounceMs = 150;        // must not be negative
    options.TypoTolerance = false;
    options.EnableHistory = false;
    options.ResetOnClose = false;    // reopen where it was left
    options.Density = "compact";
    options.Theme = "dark";
});
OptionThis siteDefaultWhat it does
ToggleShortcut mod+k mod+k Opens and closes the palette; null for none. The palette's ToggleShortcut parameter overrides it.See it →
AdditionalToggleShortcuts mod+shift+p ● none More shortcuts that do the same.See it →
SuppressShortcutsInEditableElements true true Plain keys pressed in an input, a text area or a content-editable element are typing, not shortcuts; chords with a modifier still fire.See it →
SequenceTimeoutMs 1000 1000 How long a sequence (G I) waits for its next chord. Must be positive.See it →
ShowSequenceHint true true Shows and announces a sequence in progress.See it →
Loop true true Arrowing past the last row comes back to the first.See it →
VimBindings true ● false Ctrl+J / Ctrl+K move inside the list; Ctrl+N / Ctrl+P always do.See it →
DebounceMs 150 150 Quiet time after the last keystroke before async sources are asked. Must not be negative.See it →
SourceTimeoutMs 10000 10000 How long a source may take before it counts as failed and gets a retry row; 0 waits for ever.See it →
Sources Documentation ● none Async sources asked in the default mode.See it →
Modes > # @ ? ● none Modes registered at startup.See it →
ShowModeHints true true The Modes group on the empty query.See it →
Commands none none Commands registered at startup.See it →
GroupOrder Navigation, Actions, Preferences, Danger zone, Help ● empty Groups listed first on the empty query, in this order; the rest follow.See it →
GroupWhenSearching true true Results keep their group headings while searching; false lists one flat ranked list.See it →
MaxResults 150 150 Rows kept per query, groups excluded; pinned and recent commands are listed beyond it. Must be positive.See it →
Matcher BaletteFuzzyMatcher BaletteFuzzyMatcher Scores and highlights every field: fuzzy by default, BaletteSubstringMatcher or your own.See it →
Weights 1 / 0.9 / 0.7 / 0.5 / 0.5 / 0.4 / 0.3 1 / 0.9 / 0.7 / 0.5 / 0.5 / 0.4 / 0.3 Field weights: title, keywords, subtitle, group, path, description, tags.See it →
PriorityWeight 0.25 0.25 How much a command's priority nudges its rank while searching.See it →
FrecencyWeight 6 6 How much frecency - use, weighted by how recent - nudges it.See it →
SearchNestedCommands true true Nested commands are found from the root page, with their path.See it →
TypoTolerance true true A query that found nothing is retried allowing a typo per term.See it →
HighlightMatches true true Matched characters in titles and subtitles are marked.See it →
EnableHistory true true Records recents, pins and frecency.See it →
MaxRecents 5 5 Recent commands listed on the empty query.See it →
MaxHistoryEntries 200 200 Commands the history keeps at most; pinned ones are never pruned.See it →
HistoryStorageKey bit-balette.history bit-balette.history The localStorage key of the default history store.See it →
CloseOnBackdropClick true true A click on the backdrop closes the palette.
CloseOnNavigation true true The palette closes when the app navigates.
ResetOnClose true true Closing clears the query and the pages; false reopens where it was left.
ShowFooter true true The hint bar under the list, where toasts show.See it →
ShowShortcuts true true Shortcut hints at the end of the rows.See it →
Virtualize false false Renders only the visible rows; recommended above about 500.See it →
RowHeight 44 44 A row's height in pixels while virtualized. Must be positive.See it →
Density comfortable comfortable comfortable or compact; exposed as data-density.See it →
Theme auto auto auto follows the page; light or dark forces one.See it →
Strings BaletteStrings BaletteStrings Every label and announcement.See it →
AllowedUrlSchemes http, https, mailto, tel http, https, mailto, tel Schemes an Href may use; relative links always may.See it →
RecordCommandIdsInTraces true true Whether balette.command activities carry the command's id; metrics never do.See it →

One palette's parameters

Most display options can be overridden for one palette with the parameter of the same name - an inline palette in compact density next to a comfortable modal one, as on Registering commands. The component's parameters:

ParameterWhat it does
Placeholder, StringsThe search box's placeholder, and every label and announcement (localization).
Theme, Densityauto, light or dark; comfortable or compact.
Class, Style, UnstyledExtra classes and inline custom properties on the dialog, or no library styles at all (theming). Any other attribute lands on the dialog too.
ItemTemplate, IconTemplate, GroupHeaderTemplate, EmptyTemplate, LoadingTemplate, HeaderTemplate, FooterTemplate, DetailTemplateReplace a part of the palette (templates).
Loop, VimBindings, Virtualize, ShowFooter, ShowShortcuts, HighlightMatches, EnableHistory, GroupWhenSearching, SearchNestedCommands, TypoToleranceOverride the option of the same name; left unset, the option applies.
ToggleShortcutOverrides options.ToggleShortcut for this palette.
DisablePointerSelectionHovering a row no longer moves the selection.
Inline, IncludeRegisteredCommandsA palette in the page rather than over it, and whether it lists the registry's commands, sources and modes or only its own.
Commands, child contentCommands of this palette alone: a list (re-read when it is a new collection), and BaletteGroup/BaletteItem markup.
Open / OpenChangedTwo-way binding of the open state: @bind-Open.
OnOpened, OnClosed, OnQueryChanged, OnCommandExecutedCallbacks for this palette - the last with the command, its result and how long its handler took.

The component also exposes IsOpen, Query and ActiveCommand, and OpenAsync, CloseAsync, ToggleAsync and SetQueryAsync - the same as the service's, for the code that holds a reference to it:

<Balette @ref="_palette"
         @bind-Open="_paletteOpen"
         OnOpened="..." OnClosed="..."
         OnQueryChanged="query => _lastQuery = query"
         OnCommandExecuted="e => Log($"{e.Command.Id} -> {e.Result} in {e.Duration.TotalMilliseconds} ms")" />

@code {
    private Balette _palette = default!;
    private bool _paletteOpen;

    private Task SearchFor(string text) => _palette.SetQueryAsync(text); // as if typed
    private BaletteCommand? Highlighted => _palette.ActiveCommand;
}

Security

  • Text is text. Titles, subtitles, descriptions, badges, queries and whatever an async source returns are rendered as text by Razor, never as HTML. Icons are RenderFragments you build, or a CSS class name.
  • Links are checked. A command's Href is followed only when it is relative or its scheme is in options.AllowedUrlSchemes (here: http, https, mailto, tel); a javascript:, data: or vbscript: link - read the way a browser reads it, tabs and control characters included - is refused and logged. Commands often carry API data, so this matters most for sources.
  • Errors are generic. A failed command shows BaletteStrings.CommandFailed, not the exception's text, which can name a server, a table or a user (see failures).
  • History is ids only. Recents and pins store command ids, counts and times - never queries. A source whose command ids embed personal data (an e-mail address) should set ExcludeFromHistory, or use opaque ids - as this site's directory search does. Stored history is validated when it is read: entries a hand-edited or corrupt localStorage holds are dropped.
  • Visibility is not authorization. VisibleWhen and Disabled shape the UI. Guards are asked every time a command is about to run - from a row, a shortcut or code - and refuse it when they say so (below). On WebAssembly they run in the browser, so the server must still check every action a handler asks it to perform.
  • No inline script. The browser layer is a module imported from _content/Bit.Balette/bit-balette.js, with no inline scripts and no eval: script-src 'self' is enough.
A link that is refused

This page registers Follow a javascript: link, whose Href is javascript:alert('This never runs') - the kind of value an API could hand a source. Its subtitle shows the address as plain text, and choosing it runs nothing: the palette answers with its generic failure message and logs a warning, naming the command and the scheme, to the browser's console.

options.AllowedUrlSchemes.Add("vscode");     // let commands open vscode:// links
options.AllowedUrlSchemes.Remove("tel");

BaletteCmd.New(person.Name)
    .Id($"person:{person.Id}")               // an opaque id, not the e-mail address
    .ExcludeFromHistory()                    // or keep it out of the history altogether
Guards

This page registers Purge the cache (Alt+Shift+P), guarded by the role below, and an Admin tools page whose guard covers every command under it. Both stay listed for a viewer - hiding them is VisibleWhen's job - and are refused when chosen, from their shortcut or from code, with the guard's message. Switch the role while the palette shows them: the next Enter asks again.

CommandRefused: nothing refused yet · ran: 0

BaletteCmd.New("Purge the cache").Shortcut("Alt+Shift+P")
    .Guard(_ => user.IsAdmin, "Only admins can purge the cache.")
    .Handler(PurgeAsync);

BaletteCmd.New("Admin tools")
    .Guard(async (ctx, ct) => await auth.IsAdminAsync(ct) ? true : BaletteGuardResult.Deny("Admin tools are for admins."))
    .Children(rotateKeys, auditLog);                          // guards everything under it

// Rules for many commands: one guard, resolved from the scope.
builder.Services.AddBitBaletteCommandGuard<PermissionGuard>();

Palette.CommandRefused += (_, e) => audit.Log(e.Command.Id, e.Trigger, e.Message);

Diagnostics

The palette reports through System.Diagnostics under Bit.Balette (BaletteDiagnostics.MeterName, .ActivitySourceName): how many commands ran, failed, were cancelled or refused, by kind and by what started them (balette.command.executions), how long handlers, sources and the in-memory search took (balette.command.duration, balette.source.duration, balette.search.duration), and a balette.command activity around every handler, so the calls it makes are its children. Nothing is recorded while nobody listens; no query, prompt value or title ever is, and RecordCommandIdsInTraces = false keeps ids out of traces too.

// Bit.Belemetry
builder.Services.AddBitBelemetryServices(options =>
{
    options.Metrics.Meters.Add(BaletteDiagnostics.MeterName);
    options.Traces.Sources.Add(BaletteDiagnostics.ActivitySourceName);
});

// OpenTelemetry
builder.Services.AddOpenTelemetry()
    .WithMetrics(m => m.AddMeter(BaletteDiagnostics.MeterName))
    .WithTracing(t => t.AddSource(BaletteDiagnostics.ActivitySourceName));
An unhandled error has occurred. Reload 🗙