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:

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

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.