Style Overrides

Style overrides inject CSS custom property values into the generated stylesheet. Two functions are available: WithStyleOverrides for values shared across both themes, and WithThemedStyleOverrides for values that differ between light and dark.

Theme-neutral overrides

kazari.WithStyleOverrides sets the same value for both themes:

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithStyleOverrides(map[string]string{
4
        "radius":    "0",
5
        "font-size": "14px",
6
    }),
7
)

Key normalization: bare names like radius are automatically prefixed to --kz-radius. Keys that already start with -- are used as-is, whether they begin with --kz- or not.

Universal values appear in both the light and dark CSS blocks. This ensures the value is never overridden by a theme-derived default that would otherwise win in the dark block.

Multiple WithStyleOverrides calls merge into the same internal map. When the same key appears in two calls, the later call's value is used.

Themed overrides

kazari.WithThemedStyleOverrides sets separate values per theme:

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithThemedStyleOverrides(map[string]kazari.StyleValue{
4
        "--kz-editor-bg": {Dark: "#1e293b", Light: "#ffffff"},
5
        "--kz-shadow":    {Dark: "none", Light: "0 2px 8px rgba(0,0,0,0.1)"},
6
    }),
7
)

The same key normalization rules apply. Light values appear in the :root block; dark values appear in the dark mode block. Setting only Dark or only Light is valid: the missing theme emits no line for that variable.

Both functions write to the same internal map and can be combined freely:

1
engine := kazari.New(
2
    kazari.WithHighlighter(hl),
3
    kazari.WithStyleOverrides(map[string]string{
4
        "radius": "0",
5
    }),
6
    kazari.WithThemedStyleOverrides(map[string]kazari.StyleValue{
7
        "--kz-editor-bg": {Dark: "#1e293b", Light: "#f8fafc"},
8
    }),
9
)

The StyleValue type

StyleValue carries one universal value or separate per-theme values:

1
type StyleValue struct {
2
    Value string // both themes (theme-neutral)
3
    Dark  string // dark theme only
4
    Light string // light theme only
5
}

Helper methods:

An empty string for any field means no CSS line is emitted for that slot. This makes it safe to set only one theme without producing a blank property in the other.

How overrides appear in CSS

Overrides are sorted alphabetically by key and emitted inside the root and dark blocks:

1
/* theme-neutral override: appears in both blocks */
2
:root {
3
    --kz-font-size: 14px;
4
    --kz-radius: 0;
5
}
6
7
[data-theme="dark"] {
8
    --kz-font-size: 14px;  /* universal value repeated */
9
    --kz-radius: 0;
10
}

Themed overrides split between the two blocks:

1
:root {
2
    --kz-editor-bg: #f8fafc;
3
    --kz-shadow: 0 2px 8px rgba(0,0,0,0.1);
4
}
5
6
[data-theme="dark"] {
7
    --kz-editor-bg: #1e293b;
8
    --kz-shadow: none;
9
}

Alphabetical sorting makes the CSS output deterministic across builds.

File config

Style overrides in kazari.config.yaml use the styleOverrides key with three value formats:

Plain string sets the same value for both themes:

1
styleOverrides:
2
  radius: "0.5rem"
3
  toolbar-height: "2.5rem"

Array sets dark first, light second (index 0 is dark):

1
styleOverrides:
2
  editor-bg: ["#1e293b", "#f8fafc"]
3
  editor-fg: ["#e2e8f0", "#1e293b"]

Map uses explicit dark and light keys; either may be omitted:

1
styleOverrides:
2
  shadow:
3
    dark: "none"
4
    light: "0 2px 8px rgba(0,0,0,0.1)"

Key normalization applies the same rules as the Go API. See File-Based Config for the full config file format.

Precedence

Style overrides are placed after Kazari's theme-derived defaults in the generated CSS, so overrides always win within the stylesheet. When WithCascadeLayer is active (default: @layer kazari), unlayered consumer CSS automatically takes precedence over layered overrides without !important. When layering is disabled, consumer overrides need enough specificity to win.

Go API and file config overrides write to the same internal map. The last call wins for the same key: a WithStyleOverrides call placed after WithConfigDir in kazari.New() overrides the file config value for that key.

Configuration

For the full list of --kz-* variables that can be overridden, see the CSS Variables reference.