Font Introspection#
Font introspection exposes the low-level font processing that supports VlConvert’s PDF, SVG, and HTML exports. It identifies the fonts a chart uses and can generate the @font-face CSS used to embed them in SVG and HTML. These functions are public so you can reuse them for font checks, custom web pages, or other export workflows.
The result lists resolved font families, weights, and styles for a Vega or Vega-Lite specification. Which fonts appear depends on the font settings:
Google Fonts are included when
auto_google_fontsis enabled or the family is requested throughgoogle_fonts.Fonts installed on the host or registered from a directory are listed only when
embed_local_fontsis enabled.Missing fonts are omitted when
missing_fontsisfallbackorwarn. Witherror, inspection fails. See Missing Fonts.
The default settings return an empty list, even when the chart can render with local fonts.
Inspect Local and Google Fonts#
This chart uses Inter at weight 600 for its title and the bundled Liberation Sans family for its axis labels and titles. The examples enable both font sources and set missing_fonts to error so inspection fails if a first-choice font is unavailable. Google Fonts may require network access.
Save this specification:
font-introspection.vl.json
{
"$schema": "https://vega.github.io/schema/vega-lite/v6.json",
"config": {"font": "Liberation Sans"},
"title": {"text": "Sales", "font": "Inter", "fontWeight": 600},
"data": {
"values": [
{"category": "A", "value": 28},
{"category": "B", "value": 55}
]
},
"mark": "bar",
"encoding": {
"x": {"field": "category", "type": "nominal"},
"y": {"field": "value", "type": "quantitative"}
}
}
Configure font sources and missing-font handling when starting the server:
$ vl-convert serve \
> --auto-google-fonts \
> --embed-local-fonts \
> --missing-fonts error \
> --port 3000
Save this complete body as request.json:
request.json
{
"spec": {
"$schema": "https://vega.github.io/schema/vega-lite/v6.json",
"config": {
"font": "Liberation Sans"
},
"title": {
"text": "Sales",
"font": "Inter",
"fontWeight": 600
},
"data": {
"values": [
{
"category": "A",
"value": 28
},
{
"category": "B",
"value": 55
}
]
},
"mark": "bar",
"encoding": {
"x": {
"field": "category",
"type": "nominal"
},
"y": {
"field": "value",
"type": "quantitative"
}
}
},
"include_font_face": false
}
Send it to POST /vegalite/fonts, or use POST /vega/fonts for Vega input:
$ curl http://127.0.0.1:3000/vegalite/fonts \
> -H 'Content-Type: application/json' \
> --data-binary @request.json
The response is a JSON array of font records.
Output:
[
{
"name": "Inter",
"source": {
"type": "google",
"font_id": "inter"
},
"variants": [
{
"weight": "600",
"style": "normal",
"font_face": null
}
],
"url": "https://fonts.googleapis.com/css2?family=Inter:wght@600&display=swap&text=%20%24%25%2B%2C-.%2F0123456789%3AADEFIJMNOPSTWXYabcdeghilmnoprstuvxy%E2%88%92",
"link_tag": "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css2?family=Inter:wght@600&display=swap&text=%20%24%25%2B%2C-.%2F0123456789%3AADEFIJMNOPSTWXYabcdeghilmnoprstuvxy%E2%88%92\">",
"import_rule": "@import url(\"https://fonts.googleapis.com/css2?family=Inter:wght@600&display=swap&text=%20%24%25%2B%2C-.%2F0123456789%3AADEFIJMNOPSTWXYabcdeghilmnoprstuvxy%E2%88%92\");"
},
{
"name": "Liberation Sans",
"source": {
"type": "local"
},
"variants": [
{
"weight": "400",
"style": "normal",
"font_face": null
},
{
"weight": "700",
"style": "normal",
"font_face": null
}
],
"url": null,
"link_tag": null,
"import_rule": null
}
]
Inter’s record includes a stylesheet URL, an HTML link tag, and a CSS import rule. Liberation Sans has no remote URL and appears with weight 400 for axis labels and 700 for axis titles. The font_face fields are null because these examples omit embedded font CSS.
Font subsetting keeps only the characters a chart needs, reducing the size of downloaded or embedded fonts without changing the chart’s appearance. The text= parameter in Inter’s URLs requests this subset. Set subset_fonts to false to disable subsetting.
Missing Fonts#
missing_fonts checks whether the first-choice font family is available locally or through the enabled Google Fonts settings. A local font excluded because embed_local_fonts is disabled is not missing.
Policy |
When a first-choice font is unavailable |
|---|---|
|
Continue silently and omit the missing family from the result. |
|
Log a warning, then continue and omit the missing family. |
|
Fail the inspection instead of returning font records. |
For example, change the title’s font to "VLC Missing Example Font, Liberation Sans". The examples above fail because the first family is unavailable, even though Liberation Sans can render the text. A fallback does not satisfy the first-choice check, and the result does not list the fallback face used for that text.
Warnings go through the interface’s logging system, not into the font records. See Logging and Warnings.
Font-inspection responses do not include X-VLC-Logs, so callers cannot retrieve these warnings from the response. Use --missing-fonts error when an unavailable first-choice font should fail the request.
Font introspection evaluates the chart, which can load data and consume rendering resources. Apply the same access controls and resource limits as for conversions. See Fonts and Google Fonts for registration, fallback, and embedding options.