Configuration

Edit this page

{
  ...,
  "config": {                // Configuration Object
    ...                      // - Top-level Configuration
    "axis"      : { ... },   // - Axis Configuration
    "header"    : { ... },   // - Header Configuration
    "legend"    : { ... },   // - Legend Configuration
    "mark"      : { ... },   // - Mark Configuration
    "style"     : { ... },   // - Style Configuration
    "range"     : { ... },   // - Scale Range Configuration
    "scale"     : { ... },   // - Scale Configuration
    "projection": { ... },   // - Projection Configuration
    "selection" : { ... },   // - Selection Configuration
    "title"     : { ... },   // - title Configuration
    "view"      : { ... }    // - View Configuration
    "concat"    : { ... }    // - Concat Configuration
    "facet"     : { ... }    // - Facet Configuration
    "repeat"    : { ... }    // - Repeat Configuration
    "locale"    : { ... }    // - Locale Configuration
    "aria"      : ...        // - Aria Configuration
  }
}

Vega-Lite’s config object lists configuration properties of a visualization for creating a consistent theme. (This config object in Vega-Lite is a superset of Vega config.)

The rest of this page outlines different types of config properties:

Top-level Configuration
Format Configuration
- Providing Custom Formatters
- Customize Formatter for Tooltips only
Guide Configurations
Mark Configurations
Style Configuration
Scale and Scale Range Configuration
Projection Configuration
Selection Configuration
Title Configuration
View & View Composition Configuration
Locale Configuration
ARIA Configuration

Top-level Configuration

A Vega-Lite config object can have the following top-level properties:

Property	Type	Description
autosize	String \| AutoSizeParams	How the visualization size should be determined. If a string, should be one of `"pad"`, `"fit"` or `"none"`. Object values can additionally specify parameters for content sizing and automatic resizing. Default value: `pad`
background	Color \| ExprRef	CSS color property to use as the background of the entire view. Default value: `"white"`
countTitle	String	Default axis and legend title for count fields. Default value: `'Count of Records`.
fieldTitle	String	Defines how Vega-Lite generates title for fields. There are three possible styles: `"verbal"` (Default) - displays function in a verbal style (e.g., “Sum of field”, “Year-month of date”, “field (binned)”). `"function"` - displays function using parentheses and capitalized texts (e.g., “SUM(field)”, “YEARMONTH(date)”, “BIN(field)”). `"plain"` - displays only the field name without functions (e.g., “field”, “date”, “field”).
font	String	Default font for all text marks, titles, and labels.
lineBreak	String \| ExprRef	A delimiter, such as a newline character, upon which to break text strings into multiple lines. This property provides a global default for text marks, which is overridden by mark or style config settings, and by the lineBreak mark encoding channel. If signal-valued, either string or regular expression (regexp) values are valid.
padding	Number \| Object \| ExprRef	The default visualization padding, in pixels, from the edge of the visualization canvas to the data rectangle. If a number, specifies padding for all sides. If an object, the value should have the format `{"left": 5, "top": 5, "right": 5, "bottom": 5}` to specify padding for each side of the visualization. Default value: `5`
tooltipFormat	FormatConfig	Define custom format configuration for tooltips. If unspecified, default format config will be applied.

Format Configuration

These config properties define the default number and time formats for text marks as well as axes, headers, tooltip, and legends:

Property	Type	Description
numberFormat	String	If numberFormatType is not specified, D3 number format for guide labels, text marks, and tooltips of non-normalized fields (fields without `stack: "normalize"`). For example `"s"` for SI units. Use D3’s number format pattern. If `config.numberFormatType` is specified and `config.customFormatTypes` is `true`, this value will be passed as `format` alongside `datum.value` to the `config.numberFormatType` function.
numberFormatType	String	Custom format type for `config.numberFormat`. Default value: `undefined` – This is equilvalent to call D3-format, which is exposed as `format` in Vega-Expression. Note: You must also set `customFormatTypes` to `true` to use this feature.
normalizedNumberFormat	String	If normalizedNumberFormatType is not specified, D3 number format for axis labels, text marks, and tooltips of normalized stacked fields (fields with `stack: "normalize"`). For example `"s"` for SI units. Use D3’s number format pattern. If `config.normalizedNumberFormatType` is specified and `config.customFormatTypes` is `true`, this value will be passed as `format` alongside `datum.value` to the `config.numberFormatType` function. Default value: `%`
normalizedNumberFormatType	String	Custom format type for `config.normalizedNumberFormat`. Default value: `undefined` – This is equilvalent to call D3-format, which is exposed as `format` in Vega-Expression. Note: You must also set `customFormatTypes` to `true` to use this feature.
timeFormat	String	Default time format for raw time values (without time units) in text marks, legend labels and header labels. Default value: `"%b %d, %Y"` Note: Axes automatically determine the format for each label automatically so this config does not affect axes.
timeFormatType	String	Custom format type for `config.timeFormat`. Default value: `undefined` – This is equilvalent to call D3-time-format, which is exposed as `timeFormat` in Vega-Expression. Note: You must also set `customFormatTypes` to `true` and there must not be a `timeUnit` defined to use this feature.
customFormatTypes	Boolean	Allow the `formatType` property for text marks and guides to accept a custom formatter function registered as a Vega expression.

Providing Custom Formatters

To customize how Vega-Lite formats numbers or text, you can register a custom formatter by

(1) Registering an expression function that takes a data point and an optional format property. For example, to register customFormatA, you need to register the function:

vega.expressionFunction('customFormatA', function(datum, params) {
  ...
  return "<formatted string>";
});

(2) Setting the customFormatTypes config to true.

{
  ...,
  "config": {"customFormatTypes": true}
}

(3) You can then use this custom format function with format and formatType properties in text encodings and guides (axis/legend/header).

{
  "format": <params>,
  "formatType": "customFormatA"
}

Customize Formatter for Tooltips only

Since tooltips have more screen estate and less chance of collisions, sometimes it is desirable to have a truncated format in a visualization, with a longer format in the tooltip. For example, in the visualization below, we want the y-axis to have the format d so it does not have a decimal point, so as not to have incredibly long labels, but on the tooltip it has the longer .8f. To achieve this specificity, one can add a tooltipFormat prop to their config that conforms to the FormatConfig type.

Guide Configurations

Axis Configurations

Axis configurations define default settings for axes. Properties defined under the main "axis" object are applied to all axes. Additional property blocks can target more specific axis types based on the orientation ("axisX", "axisY", "axisLeft", "axisTop", etc.), band scale type ("axisBand"), scale’s data type ("axisDiscrete", "axisQuantitative", and "axisTemporal"), or both orientation and scale/data type (e.g., "axisXTemporal"). For example, properties defined under the "axisBand" property will only apply to axes visualizing "band" scales. If multiple axis config blocks apply to a single axis, type-based options take precedence over orientation-based options, which in turn take precedence over general options.

See more details in the axis documentation.

Property	Type	Description
axis	AxisConfig	Axis configuration, which determines default properties for all `x` and `y` axes. For a full list of axis configuration options, please see the corresponding section of the axis documentation.
axisX	AxisConfig	X-axis specific config.
axisY	AxisConfig	Y-axis specific config.
axisLeft	AxisConfig	Config for y-axis along the left edge of the chart.
axisRight	AxisConfig	Config for y-axis along the right edge of the chart.
axisTop	AxisConfig	Config for x-axis along the top edge of the chart.
axisBottom	AxisConfig	Config for x-axis along the bottom edge of the chart.
axisBand	AxisConfig	Config for axes with “band” scales.
axisPoint	AxisConfig	Config for axes with “point” scales.
axisDiscrete	AxisConfig	Config for axes with “point” or “band” scales.
axisQuantitative	AxisConfig	Config for quantitative axes.
axisTemporal	AxisConfig	Config for temporal axes.
axisXBand	AxisConfig	Config for x-axes with “band” scales.
axisXPoint	AxisConfig	Config for x-axes with “point” scales.
axisXDiscrete	AxisConfig	Config for x-axes with “point” or “band” scales.
axisXQuantitative	AxisConfig	Config for x-quantitative axes.
axisXTemporal	AxisConfig	Config for x-temporal axes.
axisYBand	AxisConfig	Config for y-axes with “band” scales.
axisYPoint	AxisConfig	Config for y-axes with “point” scales.
axisYDiscrete	AxisConfig	Config for y-axes with “point” or “band” scales.
axisYQuantitative	AxisConfig	Config for y-quantitative axes.
axisYTemporal	AxisConfig	Config for y-temporal axes.

Header Configuration

Property	Type	Description
header	HeaderConfig	Header configuration, which determines default properties for all headers. For a full list of header configuration options, please see the corresponding section of in the header documentation.

Property

Type

Description

header

HeaderConfig

Header configuration, which determines default properties for all headers.

For a full list of header configuration options, please see the corresponding section of in the header documentation.

Legend Configuration

Property	Type	Description
legend	LegendConfig	Legend configuration, which determines default properties for all legends. For a full list of legend configuration options, please see the corresponding section of in the legend documentation.

Built-in Guide Styles

In addition to axis, header, and legend styles, Vega-Lite also includes the following built-in styles that are shared across different kinds of guides:

"guide-label": style for axis, legend, and header labels
"guide-title": style for axis, legend, and header titles
"group-title": styles for chart titles

See the documentation about the style configuration for more information.

Mark Configurations

The mark property of the config object sets the default properties for all marks. In addition, the config object also provides mark-specific config using its mark type as the property name (e.g., config.area) for defining default properties for each mark.

Property	Type	Description
mark	MarkConfig	Mark Config
area	AreaConfig	Area-Specific Config
bar	BarConfig	Bar-Specific Config
circle	MarkConfig	Circle-Specific Config
line	LineConfig	Line-Specific Config
point	MarkConfig	Point-Specific Config
rect	RectConfig	Rect-Specific Config
geoshape	MarkConfig	Geoshape-Specific Config
rule	MarkConfig	Rule-Specific Config
square	MarkConfig	Square-Specific Config
text	MarkConfig	Text-Specific Config
tick	TickConfig	Tick-Specific Config

Style Configuration

In addition to the axis and mark config above, default values can be further customized using named styles defined under the style block. Styles can then be invoked by including a style property within a mark definition object or an axis definition object.

See the documentation about the mark style configuration for more information about how to use style configuration to customize mark style.

Property	Type	Description
style	Object	An object hash that defines key-value mappings to determine default properties for marks with a given style. The keys represent styles names; the values have to be valid mark configuration objects.

Scale and Scale Range Configuration

Property	Type	Description
scale	ScaleConfig	Scale configuration determines default properties for all scales. For a full list of scale configuration options, please see the corresponding section of the scale documentation.
range	RangeConfig	An object hash that defines default range arrays or schemes for using with scales. For a full list of scale range configuration options, please see the corresponding section of the scale documentation.

Projection Configuration

Property	Type	Description
projection	ProjectionConfig	Projection configuration, which determines default properties for all projections. For a full list of projection configuration options, please see the corresponding section of the projection documentation.

Selection Configuration

Property	Type	Description
selection	SelectionConfig	An object hash for defining default properties for each type of selections.

Title Configuration

Property	Type	Description
title	TitleConfig	Title configuration, which determines default properties for all titles. For a full list of title configuration options, please see the corresponding section of the title documentation.

View & View Composition Configuration

Property	Type	Description
view	ViewConfig	Default properties for single view plots.
concat	CompositionConfig	Default configuration for all concatenation and repeat view composition operators (`concat`, `hconcat`, `vconcat`, and `repeat`)
facet	CompositionConfig	Default configuration for the `facet` view composition operator

Each of the view composition configurations (concat and facet) supports the following properties:

Property Type Description

columns

Number

Property	Type	Description
columns	Number	The number of columns to include in the view composition layout. Default value: `undefined` – An infinite number of columns (a single row) will be assumed. This is equivalent to `hconcat` (for `concat`) and to using the `column` channel (for `facet` and `repeat`). Note: 1) This property is only for: the general (wrappable) `concat` operator (not `hconcat`/`vconcat`) the `facet` and `repeat` operator with one field/repetition definition (without row/column nesting) 2) Setting the `columns` to `1` is equivalent to `vconcat` (for `concat`) and to using the `row` channel (for `facet` and `repeat`).
spacing	Number	The default spacing in pixels between composed sub-views. Default value: `20`

The number of columns to include in the view composition layout.

Default value: undefined – An infinite number of columns (a single row) will be assumed. This is equivalent to hconcat (for concat) and to using the column channel (for facet and repeat).

Note:

1) This property is only for:

the general (wrappable) concat operator (not hconcat/vconcat)
the facet and repeat operator with one field/repetition definition (without row/column nesting)

2) Setting the columns to 1 is equivalent to vconcat (for concat) and to using the row channel (for facet and repeat).

spacing

Number

The default spacing in pixels between composed sub-views.

Default value: 20

Repeat uses the same configuration as concatenation.

Locale Configuration

Property	Type	Description
locale	Locale	Locale definitions for string parsing and formatting of number and date values. The locale object should contain `number` and/or `time` properties with locale definitions. Locale definitions provided in the config block may be overridden by the View constructor locale option.

ARIA Configuration

Property Type Description

aria

Boolean

Property	Type	Description
aria	Boolean	A boolean flag indicating if ARIA default attributes should be included for marks and guides (SVG output only). If false, the `"aria-hidden"` attribute will be set for all guides, removing them from the ARIA accessibility tree and Vega-Lite will not generate default descriptions for marks. Default value: `true`.

A boolean flag indicating if ARIA default attributes should be included for marks and guides (SVG output only). If false, the "aria-hidden" attribute will be set for all guides, removing them from the ARIA accessibility tree and Vega-Lite will not generate default descriptions for marks.

Default value: true.