This website is for Vega-Lite v4. Go to the main Vega-Lite homepage for the latest release.

Format

Edit this page

In Vega-Lite specifications you can customize the format of text marks, tooltips, axis, legend, header labels.

The text field definition as well as definitions of axis, legend, header labels include the following properties:

Property Type Description
format String | Dict

When used with the default "number" and "time" format type, the text formatting pattern for labels of guides (axes, legends, headers) and text marks.

See the format documentation for more examples.

When used with a custom formatType, this value will be passed as format alongside datum.value to the registered function.

Default value: Derived from numberFormat config for number format and from timeFormat config for time format.
formatType String

The format type for labels. One of "number", "time", or a registered custom format type.

Default value: - "time" for temporal fields and ordinal and nominal fields with timeUnit. - "number" for quantitative fields as well as ordinal and nominal fields without timeUnit.

In addition, you can override the default formats in the config.

Formatting Text Marks and Tooltips

// A Single View or a Layer Specification
{
  ...,
  "mark/layer": ...
  "encoding": {
    ...,
    "text": {
      "field": ...,
      "type": ...,
      "format": ...,   // Format
      "formatType": ...,
      ...
    },
    ...
  }
}

Text marks and tooltips are formatted by setting the format property of text or tooltip channel definitions.

For example, we can use Vega-Lite to show the average horsepower for cars from different origins. To format the number to have 2 digits of precisions, we can use the format .2f.

Formatting tooltips or dates is done similarly.

Formatting Axis, Legend, and Header Labels

// A Single View or a Layer Specification
{
  ...,
  "mark/layer": ...,
  "encoding": {
    ...: {
      "field": ...,
      "type": ...,
      "axis/legend/header": {                // Axis / Legend / Header
        "format": ...,
        "formatType": ...,
        ...
      },
      ...
    },
    ...
  }
}

Quantitative Fields

Below, we override the default number formatting to use exponent notation set to two significant digits.

Temporal Data

In the example below we format the axis label to only show the year.

The format can also contain text.