Themes#

A theme is a named configuration object that Vega-Lite applies while compiling a specification. Themes set defaults for colors, marks, axes, legends, fonts, and other visual properties. They apply to Vega-Lite input only because Vega input skips Vega-Lite compilation. For Vega input, pass a configuration object directly with config or --config.

VlConvert bundles the themes from the vega-themes package. Select a theme per conversion, or set default_theme in the converter configuration.

Every conversion example and image on this page uses this Vega-Lite specification. Save it as follows:

chart.vl.json
{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "title": "Revenue by Quarter",
  "width": 240,
  "height": 180,
  "data": {
    "values": [
      {"quarter": "Q1", "region": "North", "revenue": 42},
      {"quarter": "Q1", "region": "South", "revenue": 31},
      {"quarter": "Q1", "region": "West", "revenue": 18},
      {"quarter": "Q2", "region": "North", "revenue": 47},
      {"quarter": "Q2", "region": "South", "revenue": 36},
      {"quarter": "Q2", "region": "West", "revenue": 24},
      {"quarter": "Q3", "region": "North", "revenue": 52},
      {"quarter": "Q3", "region": "South", "revenue": 34},
      {"quarter": "Q3", "region": "West", "revenue": 29},
      {"quarter": "Q4", "region": "North", "revenue": 61},
      {"quarter": "Q4", "region": "South", "revenue": 40},
      {"quarter": "Q4", "region": "West", "revenue": 33}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "quarter", "type": "nominal", "axis": {"labelAngle": 0}},
    "y": {"field": "revenue", "type": "quantitative"},
    "color": {"field": "region", "type": "nominal"}
  }
}

Use a Built-In Theme#

Themes included in vega-themes can be referenced by name. Visit the theme explorer to preview available themes.

from pathlib import Path

import vl_convert as vlc

spec = Path("chart.vl.json").read_text(encoding="utf-8")
svg = vlc.vegalite_to_svg(spec, theme="dark")
Path("chart.svg").write_text(svg, encoding="utf-8")

The same chart with the default configuration and with the dark theme:

Stacked bar chart of revenue by quarter with the default configuration
The same stacked bar chart with the dark theme

List and Inspect Themes#

get_themes() maps each theme name to the Vega configuration it applies:

import json

import vl_convert as vlc

themes = vlc.get_themes()
print(json.dumps(sorted(themes), indent=2), end="\n\n")
print(json.dumps(themes["dark"], indent=2))

Output:

[
  "carbong10",
  "carbong100",
  "carbong90",
  "carbonwhite",
  "dark",
  "excel",
  "fivethirtyeight",
  "ggplot2",
  "googlecharts",
  "latimes",
  "powerbi",
  "quartz",
  "urbaninstitute",
  "vox"
]

{
  "background": "#333",
  "view": {
    "stroke": "#888"
  },
  "title": {
    "color": "#fff",
    "subtitleColor": "#fff"
  },
  "style": {
    "guide-label": {
      "fill": "#fff"
    },
    "guide-title": {
      "fill": "#fff"
    }
  },
  "axis": {
    "domainColor": "#fff",
    "gridColor": "#888",
    "tickColor": "#fff"
  }
}

Register a Custom Theme#

A custom theme file is a JSON object whose keys are theme names and whose values are Vega configuration objects. Save this example as themes.json:

themes.json
{
  "brand": {
    "background": "#f7f9fc",
    "range": {"category": ["#225ea8", "#41b6c4", "#a1dab4"]},
    "axis": {
      "labelColor": "#4c5a6b",
      "titleColor": "#4c5a6b",
      "gridColor": "#dfe5ee"
    },
    "title": {"color": "#225ea8"}
  }
}

A custom theme replaces a built-in theme with the same name.

import json
from pathlib import Path

import vl_convert as vlc

themes = json.loads(Path("themes.json").read_text(encoding="utf-8"))
vlc.configure(themes=themes)
svg = vlc.vegalite_to_svg(spec, theme="brand")
Path("chart.svg").write_text(svg, encoding="utf-8")

The brand theme applied to the same input. Only the selected theme changes:

The stacked bar chart with the brand theme's blue and green palette

See Configuration to set a default theme for every conversion, and Conversion Overrides to pass a raw config object instead of a named theme.