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:
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:
See Configuration to set a default theme for every conversion, and Conversion Overrides to pass a raw config object instead of a named theme.