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

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
    "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

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

Format Configuration

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

Property Type Description
numberFormat String

D3 Number format for guide labels and text marks. For example "s" for SI units. Use D3’s number format pattern.

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.

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 new formatter by (1) registering an expression function that takes a data point and an optional format parameter and (2) setting the customFormatTypes config to true. For example, to register customFormatA, you run need to register the function:

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

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"
}

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.

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

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.

ARIA Configuration

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.