Theming & templates
The default look is a set of CSS custom properties, so restyling the palette means overriding variables - on
:root, on the dialog, or inline through the component's Style - with no selectors to fight.
Past that, every part of a row and of the dialog can be replaced with a template, or the styles left out entirely.
The controls below restyle the palette this site is using.
What the palette host hands its palette right now:
<Balette Theme="(follows the page)"
Density="(comfortable, from the options)"
Style="(none)"
DetailTemplate="_detailPane"
ShowFooter="true"
ShowShortcuts="true" />prefers-color-scheme, or <html data-theme> when an app sets one.
This site's theme is the bit-theme attribute its own toggle sets instead, so its demo.css
points the palette's custom properties at that attribute - in the brand's blue - exactly the way the tokens below are
meant to be overridden. The palette's Theme parameter (auto, light or
dark; options.Theme by default) wins over the page for the palette alone, for an app that
wants a dark palette over a light page.
The tokens
Every visual is a custom property on :root, so the trigger and the shortcut hints outside the dialog share
them with it. The library's light defaults are below; every colour has a dark value too, and every text colour pair of
the default light and dark themes meets WCAG AA (4.5:1), on the active row and the footer as well.
| Custom property | Light default | Controls |
|---|---|---|
--bit-balette-width | 640px (920px with a detail pane) | The dialog's width; it never exceeds the viewport |
--bit-balette-max-height | min(70vh, 560px) | How tall the list may grow |
--bit-balette-top | 12vh | How far down the dialog opens |
--bit-balette-radius | 14px | The dialog's corners |
--bit-balette-row-height | 44px | A row's minimum height; while Virtualize is on, options.RowHeight sets it |
--bit-balette-gap | 8px | The list's padding |
--bit-balette-font / -font-size / -mono | system stacks, 14px | The type, and key caps and code |
--bit-balette-z | 1000 | Stacking order |
--bit-balette-bg / -bg-elevated | #ffffff / #f6f7f9 | The dialog, and the detail pane and footer |
--bit-balette-fg / -fg-muted / -fg-subtle | #111318 / #5f6673 / #6b7280 | Titles; subtitles and hints; the quietest text |
--bit-balette-border | rgba(17, 19, 24, .08) | Dividers |
--bit-balette-accent / -accent-fg | #4f46e5 / white | Toggles that are on, checked rows, badges, the mode chip, the spinner |
--bit-balette-accent-soft | rgba(79, 70, 229, .10) | Behind badges, the mode chip and checked boxes |
--bit-balette-active-bg | rgba(17, 19, 24, .06) | The active row |
--bit-balette-danger / -danger-soft | #c81e1e | Destructive commands, errors, a failed source |
--bit-balette-mark-bg | rgba(79, 70, 229, .18) | Highlighted matched characters |
--bit-balette-kbd-bg / -kbd-fg / -kbd-border | #f3f4f6 | Key caps |
--bit-balette-backdrop / -backdrop-blur | rgba(17, 19, 24, .45) / 2px | The page behind the open dialog |
--bit-balette-shadow / -scrollbar | - | The dialog's shadow, the list's scrollbar |
--bit-balette-input-height / -input-font-size | 56px / 16px | The search box |
--bit-balette-item-radius / -item-padding / -item-gap | 8px / 6px 10px / 12px | Rows |
--bit-balette-heading-font-size / -footer-height / -detail-width | 11px / 40px / 40% | Group headings, the footer, the detail pane |
--bit-balette-duration | 140ms | The pop-in |
--bit-balette-heading-fg / -focus-ring / -toggle-knob | unset | Optional: group headings (else -fg-muted), focus outlines (else the accent), the switch's knob (else white) |
/* app.css - after the library's stylesheet */
:root {
--bit-balette-accent: #0d9488;
--bit-balette-width: 760px;
--bit-balette-radius: 8px;
}
:root[data-theme="dark"] {
--bit-balette-accent: #2dd4bf;
}
/* An app with a theme switch of its own points the dark values at it instead -
this site's demo.css does it for <html bit-theme="dark">. */
:root[bit-theme="dark"] {
--bit-balette-accent: #4fa3f4;
}
The MCP server's GetBaletteThemeVariables lists every one with its light and dark value, read from the
stylesheet itself (see MCP server).
What the palette adapts to
- Light and dark.
prefers-color-scheme,<html data-theme="light|dark">, or the palette's ownThemeparameter - the controls above. - Density.
Density="compact"(oroptions.Density) tightens rows, the search box and the footer for a dense application or an inline palette;comfortableis the default. The value is exposed asdata-density, so a stylesheet can define more. - Reduced motion. Under
prefers-reduced-motionthe dialog's pop-in and the switches' transitions are dropped, and the spinner slows down. - Small screens. Below 640 px the dialog fills the screen and hides the footer's hints and the detail pane.
- More contrast. Under
prefers-contrast: moreborders are drawn stronger, the active row is outlined, and highlighted characters are underlined as well as tinted. - Forced colours. In Windows High Contrast, backgrounds and shadows disappear, so the active row is
outlined in the system
Highlightcolour, the dialog gets a border, and checkboxes, switches and highlights are drawn in system colours. - Right to left. Every rule uses logical properties, so
dir="rtl"lays the palette out from the right: the footer's last hint, the detail pane's border and the switch's knob follow, arrows and chevrons are mirrored, and user text isolates its own direction (dir="auto"), so an English title in a Persian UI keeps its punctuation where it belongs. Key caps always read left to right, as on the keys.
@* Light or dark: prefers-color-scheme, <html data-theme="...">, or the palette's own Theme, which wins for it alone. *@
<Balette Theme="dark" Density="compact" />
@* Right to left: dir on the palette, or on anything around it. *@
<div dir="rtl">
<Balette />
</div>
/* data-density is any value Density is given: a stylesheet can define more than the two. */
.bit-balette-dialog[data-density="cozy"] {
--bit-balette-row-height: 38px;
--bit-balette-input-height: 48px;
--bit-balette-item-padding: 4px 9px;
}
The button sets the site's language, as the palette's Language command does - Localization goes further.
Templates
The detail pane on the right of this site's palette is a DetailTemplate in
Components/AppPalette.razor; it shows the Person record a people row carries as
Data. The other parts are replaced the same way:
| Parameter | Receives | Replaces |
|---|---|---|
ItemTemplate | BaletteItemContext: the row, and whether it is active, checked, pinned or confirming, and IsMac | A row's content (the row element, its role, ARIA state, data attributes and clicks stay the library's) |
IconTemplate | BaletteCommand | Every row's icon |
DetailTemplate | the active BaletteCommand | Adds a preview pane for the active row, Raycast style |
GroupHeaderTemplate | the heading | A group heading |
EmptyTemplate | the query | "No results" |
LoadingTemplate | - | The loading state of a lazy page |
HeaderTemplate / FooterTemplate | BaletteStateContext: query, mode, breadcrumbs, result count, active command, loading, selection, toast, IsMac | Content above the input / the hint bar |
The palette below sets all of them but the detail pane, over a list of its own (IncludeRegisteredCommands="false",
inline). Type zz for the empty state, open The archive… for the loading state, and pick a file
for the footer's toast. IconTemplate draws the icons while the rows are the library's; untick the box to
see them, as an ItemTemplate replaces the whole content of a row, icon included.
<Balette Inline="true" IncludeRegisteredCommands="false" Commands="_files">
<ItemTemplate>
@{ var file = context.Row.Command; }
<span class="file-row">
<span class="file-ext">@Extension(file.Title)</span>
<BaletteHighlightedText Text="@file.Title" Positions="context.Row.Match!.TitlePositions" />
<small>@file.Subtitle</small>
@if (context.IsActive)
{
<kbd>Enter</kbd>
}
</span>
</ItemTemplate>
<GroupHeaderTemplate>⌁ @context</GroupHeaderTemplate>
<EmptyTemplate><p role="status">No file matches “@context”.</p></EmptyTemplate>
<LoadingTemplate><p role="status">Opening the archive…</p></LoadingTemplate>
<HeaderTemplate>@context.ResultCount files</HeaderTemplate>
<FooterTemplate>@(context.Toast ?? context.ActiveCommand?.Subtitle)</FooterTemplate>
</Balette>
BaletteHighlightedText renders a text with the matched positions marked, for templates that want the
highlighting back, and BaletteShortcutHint a shortcut in the platform's symbols. A
FooterTemplate that shows Toast should give it no live role of its own: the palette's live
regions announce it already.
Unstyled
Unstyled="true" drops the bit-balette-dialog class every rule in the stylesheet is scoped to,
so what is left is bare, accessible markup to style from scratch - without the stylesheet at all, if you like. The
palette below is one, styled by a dozen rules in this site's demo.css:
<Balette Unstyled="true" Class="my-palette" />
.my-palette [data-balette="item"][data-active] { background: CanvasText; color: Canvas; }
.my-palette [data-balette="item"][data-disabled] { opacity: .5; }
.my-palette [data-balette="group-heading"] { font-size: .75rem; text-transform: uppercase; }
.my-palette [data-balette="mark"] { background: none; text-decoration: underline; }
The structure stays addressable through stable data-balette attributes: dialog
(inline for an inline palette), root, main, header,
breadcrumbs, crumb, mode, input-row, input,
spinner, selected-count, close, notice, list,
group, group-heading, item, path, label,
mark, badge, shortcut, empty, loading,
error, retry, prompt, prompt-error, footer,
toast, status, alert, detail, and trigger on the
trigger button.
A row's state is on the row: data-active, data-checked, data-disabled,
data-destructive, data-confirming, data-running, data-error,
data-kind and data-value (the command's id). The dialog carries data-open,
data-busy, data-density, data-theme, data-multiselect and
data-ready - set once its browser layer listens for keys. They are also the stable hooks for tests.