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.
Set theme beside spec in a Vega-Lite conversion request. Save this body as request.json:
request.json
{
"spec": {
"$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"
}
}
},
"theme": "dark"
}
Send it to the SVG endpoint:
$ curl http://127.0.0.1:3000/vegalite/svg \
> -H 'Content-Type: application/json' \
> --data-binary @request.json \
> --output chart.svg
The same chart with the default configuration and with the dark theme:
List and Inspect Themes#
GET /themes lists the available names, and GET /themes/{name} returns the configuration one theme applies:
$ curl http://127.0.0.1:3000/themes
$ curl http://127.0.0.1:3000/themes/dark
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.
Register custom themes when starting the server:
$ vl-convert serve \
> --themes themes.json \
> --port 3000
The themes then appear in GET /themes and can be selected by Vega-Lite conversion requests. Save this request as request.json:
request.json
{
"spec": {
"$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"
}
}
},
"theme": "brand"
}
$ curl http://127.0.0.1:3000/vegalite/svg \
> -H 'Content-Type: application/json' \
> --data-binary @request.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.