Configuration

Edit this page

{
  ...,
  "config": {                // Configuration Object
    ...                      // - Top-level Configuration
    "axis"      : { ... },   // - Axis Configuration
    "header"    : { ... },   // - Header Configuration
    "legend"    : { ... },   // - Legend Configuration
    "mark"      : { ... },   // - Mark Configuration
    "style"     : { ... },   // - Mark Style Configuration
    "range"     : { ... },   // - Scale Range Configuration
    "scale"     : { ... },   // - Scale Configuration
    "projection": { ... },   // - Projection Configuration
    "selection" : { ... },   // - Selection Configuration
    "title"     : { ... },   // - title Configuration
    "view"      : { ... }    // - View 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
Axis Configurations
Header Configuration
Legend Configuration
Mark and Mark Style Configurations
Scale and Scale Range Configuration
Projection Configuration
Selection Configuration
Title Configuration
View Configuration

Top-level Configuration

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

Property	Type	Description
autosize	String \| AutoSizeParams	Sets 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. `"fit"` is only supported for single and layered views that don’t use `rangeStep`. Default value: `pad`
background	String	CSS color property to use as the background of visualization. Default value: none (transparent)
countTitle	String	Default axis and legend title for count fields. Default value: `'Number 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”).
invalidValues	String \| Null	Defines how Vega-Lite should handle invalid values (`null` and `NaN`). If set to `"filter"` (default), all data items with null values will be skipped (for line, trail, and area marks) or filtered (for other marks). If `null`, all data items are included. In this case, invalid values will be interpreted as zeroes.
numberFormat	String	D3 Number format for axis labels and text tables. For example “s” for SI units. Use D3’s number format pattern.
padding	Number \| Object	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`
stack	String	Default stack offset for stackable mark.
timeFormat	String	Default datetime format for axis and legend labels. The format can be set directly on each axis and legend. Use D3’s time format pattern. Default value: `''` (The format will be automatically determined).

Axis Configurations

Axis configuration defines default settings for axes. Properties defined under the "axis" property in the config object are applied to all axes.

Additional property blocks can target more specific axis types based on the orientation ("axisX", "axisY", "axisLeft", "axisTop", etc.) or band scale type ("axisBand"). 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.

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	Specific axis config for y-axis along the left edge of the chart.
axisRight	AxisConfig	Specific axis config for y-axis along the right edge of the chart.
axisTop	AxisConfig	Specific axis config for x-axis along the top edge of the chart.
axisBottom	AxisConfig	Specific axis config for x-axis along the bottom edge of the chart.
axisBand	AxisConfig	Specific axis config for axes with “band” scales.

Header Configuration

Property	Type	Description
header	HeaderConfig	Header configuration, which determines default properties for all header. 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.

Mark and Mark Style 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	MarkConfig	Rect-Specific Config
geoshape	MarkConfig	Geoshape-Specific Config
rule	MarkConfig	Rule-Specific Config
square	MarkConfig	Square-Specific Config
text	TextConfig	Text-Specific Config
tick	TickConfig	Tick-Specific Config

In addition to the default mark properties 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.

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 Configuration

Property	Type	Description
view	ViewConfig	Default properties for single view plots.