This website is for Vega-Lite v3. 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"     : { ... },   // - Mark 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
  }
}

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 the whole Vega-Lite view

Default value: none (transparent)
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”).
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.
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

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 format each label automatically so this config would not affect axes.

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.) 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 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 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 RectConfig

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

See the documentation about the style configuration for more information.

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

View & View Composition Configuration

Property Type Description
view ViewConfig

Default properties for single view plots.
concat CompositionConfig

Default configuration for all concatenation view composition operators (concat, hconcat, and vconcat)
facet CompositionConfig

Default configuration for the facet view composition operator
repeat CompositionConfig

Default configuration for the repeat view composition operator

Each of the view composition configurations (concat, facet, repeat) 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