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 VlOpts.theme for the conversion:
use vl_convert_rs::{VlConverter, VlOpts};
let spec = std::fs::read_to_string("chart.vl.json")?;
let converter = VlConverter::new();
let options = VlOpts {
theme: Some("dark".to_string()),
..Default::default()
};
let output = converter
.vegalite_to_svg(spec, options, Default::default())
.await?;
std::fs::write("chart.svg", output.svg)?;
The same chart with the default configuration and with the dark theme:
List and Inspect Themes#
get_themes() returns the same mapping as a JSON value:
let themes = converter.get_themes().await?;
println!("{}", 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.
use std::collections::HashMap;
use vl_convert_rs::{serde_json, VlcConfig, VlConverter, VlOpts};
let themes: HashMap<String, serde_json::Value> =
serde_json::from_str(include_str!("../themes.json"))?;
let converter = VlConverter::with_config(VlcConfig {
themes,
..Default::default()
})?;
let spec = std::fs::read_to_string("chart.vl.json")?;
let output = converter
.vegalite_to_svg(
spec,
VlOpts {
theme: Some("brand".to_string()),
..Default::default()
},
Default::default(),
)
.await?;
std::fs::write("chart.svg", output.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.