Configuration

Edit this page
{
  ...,
  "config": {             // Configuration Object
    ...                   // - Top-level Configuration
    "axis": { ... },      // - Axis Configuration
    "legend": { ... },    // - Legend Configuration
    "mark": { ... },      // - Mark Configuration
    "style": { ... },     // - Mark Style Configuration
    "range": { ... },     // - Scale Range Configuration
    "scale": { ... },     // - Scale 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

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

Defines how Vega-Lite should handle invalid values (null and NaN).

  • If set to "filter" (default), all data items with null values are filtered.
  • 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: '%b %d, %Y'.

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.

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 MarkConfig

Area-Specific Config

bar BarConfig

Bar-Specific Config

circle MarkConfig

Circle-Specific Config

line MarkConfig

Line-Specific Config

point MarkConfig

Point-Specific Config

rect MarkConfig

Rect-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 value are 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.

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.