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:

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() 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:

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.