Custom Theming for Vizly Charts

Vizly themes control colors, background, and chart chrome. The library ships 16 built-in themes, and you can create your own presets, load them from JSON files, or override on a per-chart basis. A theme is just a dict, so it is easy to understand and extend.

Built-in themes

import vizly as vz

# Product themes
vz.set_theme("corporate")    # default, light, dark, corporate, minimal, contrast
vz.set_theme("ops_grafana")  # ops_grafana, ops_cloudwatch, ops_kibana
vz.set_theme("editor_monokai")  # editor_monokai, editor_tokyo_night, and more

Per-chart override

Pass theme= to any chart factory to override the session theme for that chart only. The session theme stays untouched.

vz.set_theme("corporate")

chart = vz.bar(
    data,
    x="region",
    y="sales",
    title="Sales",
    theme="editor_tokyo_night",
)

Registering a custom theme

A theme is a dict with an optional palette. Register it by name, then use it like any built-in.

vz.register_theme("acme", {
    "background": "#FFFFFF",
    "palette": ["#0B1F33", "#2F6FED", "#FF6B35"],
})

vz.set_theme("acme")
chart = vz.line(data, x="date", y="value", title="Branded series")

Loading a theme from a JSON file

Keep themes in version-controlled JSON files. load_theme() reads one, with options to activate it and register it by name.

vz.load_theme("themes/atlantic.json", activate=True, register=True)

The file can use the same shape as a registered theme:

{
  "background": "#0A0A0A",
  "palette": ["#04536F", "#FF6B35", "#FFE66D"]
}

Exporting a theme

Save a registered theme back to a file for reuse across projects.

vz.export_theme("acme", "acme.json")

Deep-merge overrides

Pass a dict to set_theme to deep-merge overrides into the current theme. This is handy for small tweaks without defining a full preset.

vz.set_theme({"palette": ["#0B1F33", "#2F6FED"]})

Fine control with merge_option

For chrome that is not theme-level, merge raw ECharts option fragments directly. This runs after theme application, so it wins.

chart = vz.bar(data, x="region", y="sales", title="Sales")
chart.merge_option({
    "title": {"left": "center", "top": 0},
    "legend": {"top": "bottom", "left": "center"},
    "grid": {"top": 40, "bottom": 72, "containLabel": True},
})

Inspecting themes

List available themes to see what is registered.

vz.list_themes()

Tips

Tip	Detail
Themes are dicts	A theme needs a background and palette at minimum. Everything else is optional chrome.
Per-chart wins	theme= on a chart overrides the session theme without mutating it.
Version control themes	Store themes as JSON files and load them with load_theme for reproducibility.
merge_option is last	Use merge_option for one-off layout tweaks that should beat theme defaults.