Image Size and Quality Recommendations#

Prefer vector output when the consumer supports it. SVG works well in web pages and supports later manual editing. PDF works well for printing directly, and for embedding in LaTeX or Typst documents. Neither needs a fixed pixel size.

Use PNG when the consumer needs a high quality raster format. Use JPEG when a smaller file matters more than image quality.

Chart Size#

The specification’s width and height control chart layout, not necessarily the final exported size. With the default autosize: "pad", they size the plotting area, and Vega expands the output to include axes, legends, titles, and padding.

To request fixed outer dimensions, set autosize to {"type": "fit", "contains": "padding"} in the specification. This shrinks the plotting area to make room for the surrounding content and includes padding within the requested size. See Vega autosize and Vega-Lite sizing for supported layouts, fitting limitations, and other sizing modes.

VlConvert exports the resulting layout. A chart fitted to 640 × 360 has those dimensions in SVG and produces a 640 × 360 PNG at the default scale=1 and ppi=72. With scale=2, the same layout produces a 1280 × 720 PNG. The pixel-density settings below change the raster resolution without changing the layout.

Pixel Density#

scale multiplies the pixel dimensions of PNG and JPEG output without changing the layout. 2 is a common choice for high-density displays.

PNG also accepts ppi, which records pixels-per-inch metadata in the file and contributes to the pixel dimensions:

effective scale = scale * ppi / 72

The defaults are scale=1 and ppi=72. Either scale=2 or ppi=144 doubles the pixel dimensions. Set both only when you want the effects multiplied.

Some consumers use the ppi metadata to preserve the image’s physical size when you increase ppi for higher resolution without changing scale.

JPEG Quality#

quality ranges from 0 through 100 and defaults to 90. Higher values keep more detail and produce larger files.

Examples#

The examples use the input from Quick Start:

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"}
  }
}
$ vl-convert vl2png \
>   --input chart.vl.json --output chart.png \
>   --width 640 --height 360 --scale 2

$ vl-convert vl2jpeg \
>   --input chart.vl.json --output chart.jpg \
>   --width 640 --height 360 --quality 90

PNG output uses Vega’s canvas renderer. JPEG and PDF are produced from the SVG rendering. SVG input is converted directly by Rust image and PDF libraries without running Vega, and width and height do not apply to it. See Conversion Overrides for every per-conversion option.