theme-picker

Theme selection component for color mode (light/dark/auto), brand themes, and color accents.

Overview

The <theme-picker> component provides a UI for users to select their preferred color mode and brand theme. It integrates with ThemeManager for persistence and system preference detection.

Inline Variant

For settings pages, use the inline variant which is always visible:

Compact Mode

For high-theme-count scenarios (mobile menus, narrow sidebars), add compact to render the theme section as a grouped <select> dropdown instead of the swatch grid. This works with both popover and inline variants.

Trigger Variants

Text Button

Simple text trigger:

Icon-Only Button

For compact layouts, use an icon-only trigger with an accessible label:

Custom Styling

Apply button variant classes to match your design:

Attributes

Attribute Values Default Description
variant popover, inline popover Display mode - popover with trigger or always visible
compact boolean - Render theme section as grouped select dropdown instead of swatch grid
open boolean - Reflected attribute indicating open state (popover only)

ThemeManager API

For programmatic theme control, use the ThemeManager module:

Available Themes

Color Modes

Mode Description
auto Follows system preference (prefers-color-scheme)
light Forces light mode
dark Forces dark mode

Color Accents

Color accents are applied via ThemeManager.setAccent():

Accent Primary Hue Description
default 260 (purple) Default brand colors
ocean 200 (teal) Cool blue-green palette
forest 145 (green) Natural earthy greens
sunset 25 (orange) Warm orange-red palette

Creating Custom Themes

Create new brand themes by copying the template:

Edit the hue values (0-360):

Register in src/tokens/themes/index.css:

Hue Reference

Hue Range Colors
0-30Red / Orange
30-60Orange / Yellow
60-120Yellow / Green
120-180Green / Cyan
180-240Cyan / Blue
240-300Blue / Purple
300-360Purple / Red

Preventing FOUC

To prevent a flash of unstyled content, add this inline script to your HTML <head>:

Events

Event Detail Description
theme-picker:open - Fired when popover opens
theme-picker:close - Fired when popover closes
vb:theme-change { mode, brand, effectiveMode } Fired on window when theme changes

Accessibility

  • Popover uses role="dialog" with aria-label
  • Radio groups use proper role="radiogroup"
  • Trigger button announces expanded state via aria-expanded
  • Escape key closes the popover
  • Focus is trapped within popover when open
↑