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"}
  }
}

Put overrides beside spec in the request body. Save this body as request.json:

request.json
{
  "spec": {
    "$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"
      }
    }
  },
  "theme": "dark",
  "width": 640,
  "height": 360,
  "scale": 2
}

Send it to the PNG endpoint:

$ curl http://127.0.0.1:3000/vegalite/png \
>   -H 'Content-Type: application/json' \
>   --data-binary @request.json \
>   --output chart.png

Per-request google_fonts requires --allow-google-fonts, and per-request vega_plugin requires --allow-per-request-plugins. See Enable Per-Request Plugins.