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.
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.
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";
});
| Option | This site | Default | What 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:
| Parameter | What it does |
|---|---|
Placeholder, Strings | The search box's placeholder, and every label and announcement (localization). |
Theme, Density | auto, light or dark; comfortable or compact. |
Class, Style, Unstyled | Extra 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, DetailTemplate | Replace a part of the palette (templates). |
Loop, VimBindings, Virtualize, ShowFooter, ShowShortcuts, HighlightMatches, EnableHistory, GroupWhenSearching, SearchNestedCommands, TypoTolerance | Override the option of the same name; left unset, the option applies. |
ToggleShortcut | Overrides options.ToggleShortcut for this palette. |
DisablePointerSelection | Hovering a row no longer moves the selection. |
Inline, IncludeRegisteredCommands | A 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 content | Commands of this palette alone: a list (re-read when it is a new collection), and BaletteGroup/BaletteItem markup. |
Open / OpenChanged | Two-way binding of the open state: @bind-Open. |
OnOpened, OnClosed, OnQueryChanged, OnCommandExecuted | Callbacks 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
Hrefis followed only when it is relative or its scheme is inoptions.AllowedUrlSchemes(here:http, https, mailto, tel); ajavascript:,data:orvbscript: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 corruptlocalStorageholds are dropped. - Visibility is not authorization.
VisibleWhenandDisabledshape 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 noeval:script-src 'self'is enough.
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
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));