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.

$ vl-convert vl2svg \
>   --input chart.vl.json --output chart.svg \
>   --theme dark

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#

ls-themes prints the available names:

$ vl-convert ls-themes
carbong10
carbong100
carbong90
carbonwhite
dark
excel
fivethirtyeight
ggplot2
googlecharts
latimes
powerbi
quartz
urbaninstitute
vox

cat-theme prints the configuration a theme applies. dark is the shortest:

$ vl-convert cat-theme dark
{
  "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.

$ vl-convert --themes themes.json \
>   vl2svg --theme brand --input chart.vl.json --output chart.svg

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.