Skip to content

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.

This site's palette

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" />
The library follows 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 propertyLight defaultControls
--bit-balette-width640px (920px with a detail pane)The dialog's width; it never exceeds the viewport
--bit-balette-max-heightmin(70vh, 560px)How tall the list may grow
--bit-balette-top12vhHow far down the dialog opens
--bit-balette-radius14pxThe dialog's corners
--bit-balette-row-height44pxA row's minimum height; while Virtualize is on, options.RowHeight sets it
--bit-balette-gap8pxThe list's padding
--bit-balette-font / -font-size / -monosystem stacks, 14pxThe type, and key caps and code
--bit-balette-z1000Stacking order
--bit-balette-bg / -bg-elevated#ffffff / #f6f7f9The dialog, and the detail pane and footer
--bit-balette-fg / -fg-muted / -fg-subtle#111318 / #5f6673 / #6b7280Titles; subtitles and hints; the quietest text
--bit-balette-borderrgba(17, 19, 24, .08)Dividers
--bit-balette-accent / -accent-fg#4f46e5 / whiteToggles that are on, checked rows, badges, the mode chip, the spinner
--bit-balette-accent-softrgba(79, 70, 229, .10)Behind badges, the mode chip and checked boxes
--bit-balette-active-bgrgba(17, 19, 24, .06)The active row
--bit-balette-danger / -danger-soft#c81e1eDestructive commands, errors, a failed source
--bit-balette-mark-bgrgba(79, 70, 229, .18)Highlighted matched characters
--bit-balette-kbd-bg / -kbd-fg / -kbd-border#f3f4f6Key caps
--bit-balette-backdrop / -backdrop-blurrgba(17, 19, 24, .45) / 2pxThe page behind the open dialog
--bit-balette-shadow / -scrollbar-The dialog's shadow, the list's scrollbar
--bit-balette-input-height / -input-font-size56px / 16pxThe search box
--bit-balette-item-radius / -item-padding / -item-gap8px / 6px 10px / 12pxRows
--bit-balette-heading-font-size / -footer-height / -detail-width11px / 40px / 40%Group headings, the footer, the detail pane
--bit-balette-duration140msThe pop-in
--bit-balette-heading-fg / -focus-ring / -toggle-knobunsetOptional: 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 own Theme parameter - the controls above.
  • Density. Density="compact" (or options.Density) tightens rows, the search box and the footer for a dense application or an inline palette; comfortable is the default. The value is exposed as data-density, so a stylesheet can define more.
  • Reduced motion. Under prefers-reduced-motion the 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: more borders 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 Highlight colour, 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:

ParameterReceivesReplaces
ItemTemplateBaletteItemContext: the row, and whether it is active, checked, pinned or confirming, and IsMacA row's content (the row element, its role, ARIA state, data attributes and clicks stay the library's)
IconTemplateBaletteCommandEvery row's icon
DetailTemplatethe active BaletteCommandAdds a preview pane for the active row, Raycast style
GroupHeaderTemplatethe headingA group heading
EmptyTemplatethe query"No results"
LoadingTemplate-The loading state of a lazy page
HeaderTemplate / FooterTemplateBaletteStateContext: query, mode, breadcrumbs, result count, active command, loading, selection, toast, IsMacContent 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.

All files · 6 files
The archive… Loads for a second
Program.cs src/Server
App.razor src/Client
README.md /
appsettings.json src/Server
site.css src/Client/wwwroot
<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:

Apples6 left
BananasRipe
CherriesOut of season
Carrots1 kg
Leeks3
Throw out the leftovers
<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.

An unhandled error has occurred. Reload 🗙