Customization

Start from a light or dark Theme and override the semantic colors, layout values, or ThemeBuilder::components recipes your application needs. Theme::builder(id, base) names the result, and derived color values follow the base token they came from. Empty component styles keep stock HeroUI metrics.

The builder

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26use gpui::px;
use herogpui::core::{oklch, Color, FieldVariant};
use herogpui::theme::{
    snow, ButtonStyle, ComponentTheme, ComponentThemes, SelectStyle, SliderStyle, Theme,
};

let violet = Theme::builder("violet", Theme::light())
    .accent(oklch(0.55, 0.23, 295.0))   // hover / soft / focus all derive
    .role(Color::Success, oklch(0.73, 0.19, 150.0), snow())
    .radius(px(6.))                     // field_radius follows at 1.5x
    .components(
        ComponentThemes::default()
            .slider(ComponentTheme::new(SliderStyle::default().radius(px(9999.))))
            .select(
                ComponentTheme::new(SelectStyle::default().variant(FieldVariant::Secondary))
                    .recipe("compact", SelectStyle::default().height(px(28.))),
            )
            .button(ComponentTheme::new(ButtonStyle::default()).recipe(
                "compact",
                ButtonStyle::default().style(|el| el.h(px(28.)).px(px(10.))),
            )),
    )
    .build();

herogpui::theme::set_theme(violet, cx);
Button::new("ok").label("OK").recipe("compact");

Every method the builder exposes:

Overriding a base token

Override a base token and its derived values follow. The override replaces the input while preserving the mix weights: a role's hover and soft ratios carry over, --focus keeps tracking --accent, and a foreground override flows into soft_foreground at render time without rebuilding the theme.

1
2
3
4
5
6
7// Override one base token; every derived value follows.
let violet = Theme::builder("violet", Theme::light())
    .accent(oklch(0.55, 0.23, 295.0))
    .build();

// `accent.hover()` and `accent.soft()` are the same color-mix
// expressions, so they move with the base color.

Registering the result

set_theme(theme, cx) registers the theme under its id, activates it, and schedules every open window to repaint. The built-ins stay registered, so use_theme("light", cx) switches back — and a theme registered with set_theme is thereafter switchable to by id like any other. See Dark Mode for the switching rules. Renderers resolve Theme.components from the active provider each frame, so a later set_theme updates every .recipe("name") call site without rebuilding those builders.

Colour maths

The color functions used by the theme crate are public in herogpui-core. Use them to create OKLCH values, mix colors in Oklab and choose readable foregrounds:

1
2
3
4
5
6
7
8
9
10use herogpui::core::{
    oklch, oklcha, mix_oklab, soft_mix, with_alpha, readable_color,
};

let brand    = oklch(0.55, 0.23, 295.0);   // lightness, chroma, hue
let translucent = oklcha(0.55, 0.23, 295.0, 0.6);
let hover    = mix_oklab(brand, foreground, 0.10);  // 10% toward the foreground
let soft     = soft_mix(brand, 0.15);               // 15% over transparent
let faint    = with_alpha(brand, 0.4);
let label    = readable_color(brand);               // a readable foreground for it