Theming

Mosaico ships with three built-in theme families: Catppuccin, Rosé Pine, and Tokyo Night. Each family has multiple flavors that share a common palette and only differ in shading, so the focus borders, monocle border, unfocused borders, and the status bar all stay coordinated.

Configuration

Set the theme name and flavor in config.toml:

[theme]
name = "catppuccin"   # catppuccin, rose-pine, tokyo-night
flavor = "mocha"

Available Themes

Catppuccin

Flavor	Style
`latte`	Light
`frappe`	Medium-dark
`macchiato`	Dark
`mocha`	Darkest (default)

Rosé Pine (`name = "rose-pine"`)

Flavor	Style
`main`	Dark, default
`moon`	Slightly lighter dark
`dawn`	Light

Tokyo Night (`name = "tokyo-night"`)

Flavor	Style
`night`	Dark, default
`storm`	Dark with bluish tint
`day`	Light

Named Colors

When a theme is active, you can use named colors anywhere a color value is expected (borders, bar colors). Each theme family exposes its own palette, plus a small set of common aliases (red, green, blue, yellow) that resolve under every theme so portable configs like focused = "blue" look right regardless of which theme you pick.

Catppuccin (14 accent colors)

Name	Description
`rosewater`	Warm pink
`flamingo`	Soft pink
`pink`	Pink
`mauve`	Purple
`red`	Red
`maroon`	Dark red
`peach`	Orange
`yellow`	Yellow
`green`	Green
`teal`	Teal
`sky`	Light blue
`sapphire`	Blue
`blue`	Vivid blue
`lavender`	Soft purple

Rosé Pine

Name	Description
`love`	Red/pink accent (alias `red`)
`gold`	Warm yellow (alias `yellow`)
`rose`	Soft pink
`pine`	Teal/blue accent (alias `blue`)
`foam`	Cyan (alias `green`, `teal`)
`iris`	Purple (alias `mauve`, `purple`, `magenta`)

Tokyo Night

Name	Description
`red`	Red
`orange`	Orange
`yellow`	Yellow
`green`	Green
`cyan`	Cyan
`teal`	Teal
`blue`	Blue
`purple`	Purple
`magenta`	Magenta (alias `mauve`)

These tables list every name each theme has. No theme names its background, surface or text shades: write those as hex values, or leave the setting empty to fall back to its default.

Color Resolution

Colors are resolved in the following order:

Hex value ("#1e1e2e") – used as-is
Named color ("blue") – looked up in the active theme palette
Empty string – falls back to the default for that setting

Existing hex color values in your configuration continue to work unchanged after enabling a theme. Named colors are optional.

Examples

Using named colors in bar.toml:

[colors]
foreground = "lavender"  # a Catppuccin name
accent = "blue"          # a name every theme has

Using named colors for borders in config.toml:

[borders.colors]
focused = "blue"
monocle = "green"

Hot-Reload

Theme changes in config.toml are hot-reloaded. When the theme or its flavor changes, every named color is resolved again against the new palette: the bar’s [colors], each bar widget’s color (such as the red of the paused widget) and the border colors. Colors you leave empty take the new theme’s defaults, and hex colors stay as written. The bar and the borders update without restarting.

A name the new theme does not have, such as Rose Pine’s pine after a switch to Catppuccin, is left as written, so mosaico draws its built-in fallback in its place (for a widget, its fallback text color and no outline), the same as after a restart. To keep a color across theme families, use a name every family has (red, blue, green, yellow) or a hex value.

Keyboard shortcuts

Mosaico