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 Format

The text format specifier for formatting number and date/time in labels of guides (axes, legends, headers) and text marks.

If the format type is "number" (e.g., for quantitative fields), this is a D3’s number format pattern string.

If the format type is "time" (e.g., for temporal fields), this is either: a) D3’s time format pattern if you desire to set a static time format.

b) dynamic time format specifier object if you desire to set a dynamic time format that uses different formats depending on the granularity of the input date (e.g., if the date lies on a year, month, date, hour, etc. boundary).

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

Default

By default, time fields may have dynamic time format that uses different formats depending on the granularity of the input date (e.g., if the tick’s date lies on a year, month, date, hour, etc. boundary).

Specifying Dynamic Time Format

We can override dynamic time format by setting format to an object where the keys are valid Vega time units (e.g., year, month, etc) and the values are d3-time-format specifier strings.

Specifying Static Time Format

If you prefer using a static time format, you can set format to a desired time format specifier string:

Note that time format can also contain text.