Conversion Overrides#

An override changes one conversion without affecting the converter configuration. Use Configuration instead when the same value should apply to every conversion.

Override

Applies to

Effect

theme

Vega-Lite

Applies a built-in or custom theme

config

Vega-Lite and Vega

Merges a Vega or Vega-Lite configuration object into the input

format_locale

Vega-Lite and Vega

Selects number formatting rules

time_format_locale

Vega-Lite and Vega

Selects date and time formatting rules

background, width, height

Vega-Lite and Vega

Sets the chart background and logical size before rendering

scale

PNG and JPEG

Multiplies raster pixel dimensions

ppi

PNG

Combines with scale as scale * ppi / 72

quality

JPEG

Sets encoding quality from 0 through 100, default 90

bundle

SVG and HTML

Embeds fonts and images in SVG, or browser dependencies in HTML

renderer

HTML

Selects svg, canvas, or hybrid rendering in the browser

vl_version

Vega-Lite

Selects a bundled Vega-Lite compiler version

google_fonts

Vega-Lite and Vega

Makes selected Google Fonts available to one conversion

vega_plugin

Vega-Lite and Vega

Registers plugin code for one conversion

fullscreen

Vega Editor URLs

Selects the full-screen editor URL form

SVG input conversions accept only the raster options scale, ppi, and quality. Chart options such as theme, width, and height do not apply to them.

The examples override this Vega-Lite input:

chart.vl.json
{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "data": {
    "values": [
      {"category": "A", "value": 28},
      {"category": "B", "value": 55},
      {"category": "C", "value": 43},
      {"category": "D", "value": 91},
      {"category": "E", "value": 81}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "category", "type": "nominal"},
    "y": {"field": "value", "type": "quantitative"}
  }
}

Pass overrides as keyword arguments:

from pathlib import Path

import vl_convert as vlc

spec = Path("chart.vl.json").read_text(encoding="utf-8")
png = vlc.vegalite_to_png(
    spec,
    scale=2,
    width=640,
    height=360,
    theme="dark",
)
Path("chart.png").write_bytes(png)

A per-call vega_plugin also requires allow_per_request_plugins=True in configure(). See Enable Per-Request Plugins.

Font inspection also accepts per-call auto_google_fonts and subset_fonts overrides. See Font Introspection.