Fonts and Google Fonts#

Vega displays text in charts using fonts. VlConvert loads fonts installed on the host, and to ensure that a suitable fallback font is always available, it bundles Liberation Sans. Additionally, you can register fonts located in specific directories, or request fonts from Google Fonts.

Missing font handling#

missing_fonts decides what happens when a specification’s first-choice font is unavailable. fallback substitutes silently and is the default, warn records a warning, and error fails the conversion.

Make Fonts Available#

Configure fonts before converting a chart.

Pass font directories and Google Font requests as global options. This command uses chart.vl.json from the Roboto Slab example in the next section:

$ vl-convert \
>   --font-dir /opt/app/fonts \
>   --google-font 'Inter:400,700italic' \
>   --missing-fonts error \
>   vl2png --input chart.vl.json --output chart.png

--auto-google-fonts downloads missing first-choice fonts automatically.

Render with a Google Font#

This specification sets config.font to Roboto Slab, a family few hosts have installed. Save it as follows:

chart.vl.json
{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "title": "Set in Roboto Slab",
  "width": 320,
  "height": 160,
  "config": {"font": "Roboto Slab"},
  "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", "axis": {"labelAngle": 0}},
    "y": {"field": "value", "type": "quantitative"}
  }
}

Request the family from Google Fonts and render the chart as PNG:

$ vl-convert --google-font "Roboto Slab" \
>   vl2png --input chart.vl.json --output chart.png --scale 2

VlConvert downloads Roboto Slab on the first conversion, caches it, and lays out and rasterizes the text with it. The PNG output:

Bar chart whose title and labels are set in the Roboto Slab typeface

Without the request, the text falls back to the default sans-serif font. With missing_fonts set to error, the conversion fails instead.

Limit Automatic Downloads#

google_font_variant_threshold limits further font requests once a conversion has resolved that many Google Font variants. Configured, per-conversion, and automatically discovered families all count toward it. At or above the threshold, the next font request fails the conversion. A single request can take the total above the threshold when it resolves several variants.

Google Fonts downloads are controlled by these font options only. allowed_base_urls governs data and image URLs and has no effect on fonts.

Google Fonts Cache#

Downloaded Google Fonts are cached on disk and reused across conversions and process restarts. The cache holds both the Google Fonts CSS responses and the font files. Its directory is the platform cache directory plus vl-convert/google-fonts, such as ~/.cache/vl-convert/google-fonts on Linux or ~/Library/Caches/vl-convert/google-fonts on macOS. Set the VLC_GOOGLE_FONTS_CACHE_DIR environment variable to move it, or set it to none to disable caching and download fonts on every conversion. Set the variable before starting VlConvert.

Cached font files are evicted least-recently-used once they exceed a 512 MB cap. The cap applies to the whole process and can be changed at runtime.

$ vl-convert --google-fonts-cache-size-mb 128 \
>   vl2png --input chart.vl.json --output chart.png

A value of 0 selects the default cap.

Embed Fonts in SVG and HTML#

Set embed_local_fonts to include the fonts a chart uses as base64 @font-face rules in SVG and HTML output. VlConvert subsets embedded fonts by default so the output contains only the glyphs the chart uses on first render. Set subset_fonts to false when the text may change later. Passing bundle to an SVG conversion also embeds its fonts and images so the file is self-contained.

PNG and JPEG contain rendered pixels, and PDF output always embeds the fonts it needs, so consumers of those formats do not need the font files.

Embedding increases output size and redistributes the font file, so confirm that the font license permits it.

See Font Introspection to list the fonts VlConvert resolves for a chart.