Config

A config object defines default visual values to set a visualization’s theme.

The Vega parser accepts a JSON configuration file that defines default settings for a variety of visual encoding choices. Different configuration files can be used to “theme” charts with a customized look and feel. A configuration file is simply a JSON object with a set of named properties, grouped by type. To provide a configuration file at parse-time, simply pass an additional parameter to the parse method:

var runtime = vega.parse(spec, config);

In addition, Vega JSON specifications may contain a single, top-level config property to override any configuration settings. Any configuration provided within the specification itself will take precedence over external configurations passed to the parser.

For example, this Vega spec includes light-gray axis grid lines by default:

{
  "width": 500,
  "height": 200,
  "config": {
    "axis": {
      "grid": true,
      "gridColor": "#dedede"
    }
  },
  ...
}

Config Reference

View Properties

Properties defined in the top-level scope of the configuration object.

Property Type Description
autosize String | Object Default automatic sizing setting. Valid string values are "pad", "fit" or "none". See the autosize documentation for more.
background Color Background color of the view component, or null for transparent.
group Object Default properties for the top-level group mark representing the data rectangle of a chart. Valid properties of this object are mark properties such as "fill", "stroke" and "strokeWidth".

Usage

Set default view background and chart plotting area background colors:

{
  "background": "white",
  "group": {
    "fill": "#dedede"
  }
}

Back to Top

Event Properties

Properties for event handling configuration, defined within an "events" property block.

Property Type Description
defaults Object An object describing which events that originate within the Vega view should have their default behavior suppressed by invoking the event.preventDefault method. The defaults object should have a single property: either "prevent" (to indicate which events should have default behavior suppressed) or "allow" (to indicate only those events whose default behavior should be allowed). This property accepts either a boolean value (to prevent/allow all events) or an array of event type strings.

Usage

To prevent the default behavior for all events originating within a Vega view:

"events": {
  "defaults": {
    "prevent": true
  }
}

To prevent the default behavior for all events originating within a Vega view, except for wheel events:

"events": {
  "defaults": {
    "allow": ["wheel"]
  }
}

Back to Top

Mark Properties

Properties defining default property values for each mark type. These properties are defined within blocks with names matching a valid mark type (e.g., "area", "line", "rect"). The valid properties within each block consist of the legal mark properties (e.g., "fill", "stroke", "size", "font"). Global defaults for all mark types can be set using the "mark" property.

Important limitations:

  • Defaults for fill or stroke color will be applied only if neither "fill" nor "stroke" are defined in the Vega spec.
  • Defaults set using the top-level "mark" property will be overridden by any defaults defined for more specific mark types (e.g., "rect"). Vega’s built-in configuration includes default fill or stroke colors for a number of specific mark types, and these will take precedence over new fill or stroke colors set only on the top-level "mark".

Usage

To set a default fill color and size for symbol marks:

{
  "symbol": {
    "fill": "steelblue",
    "size": 64
  }
}

To set a global opacity value for all mark types:

{
  "mark": {
    "opacity": 0.8
  }
}

Back to Top

Style Properties

In addition to the default mark properties above, default values can be further customized using named styles defined under the style block in the config. Styles can then be invoked by including a style directive within a mark definition.

For example, to set a default shape and stroke width for symbol marks with a style named "square":

"style": {
  "square": {
    "shape": "square",
    "strokeWidth": 2
  }
}

In addition to custom style names, Vega includes the following built-in style names:

  • guide-label: styles for axis and legend labels
  • guide-title: styles for axis and legend titles
  • group-title: styles for chart and header titles

Style settings take precedence over default mark settings, but are overridden by the axis, legend, and title properties described below.

Back to Top

Axis Properties

Properties defining default settings for axes. These properties are defined under the "axis" property in the config object, in which case the settings apply 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
bandPosition Number An interpolation fraction indicating where, for band scales, axis ticks should be positioned. A value of 0 places ticks at the left edge of their bands. A value of 0.5 places ticks in the middle of their bands.
domain Boolean Boolean flag indicating if axis domain line should be included by default.
domainColor Color Color of axis domain line.
domainDash Number[ ] Stroke dash of axis domain lines (or [] for solid lines). ≥ 5.0
domainDashOffset Number The pixel offset at which to start the domain dash array. ≥ 5.0
domainOpacity Number Opacity of axis domain line. ≥ 4.1
domainWidth Number Stroke width of axis domain line.
grid Boolean Boolean flag indicating if axis grid lines should be included by default.
gridColor Color Color of axis grid lines.
gridDash Number[ ] Stroke dash of axis grid lines (or [] for solid lines).
gridDashOffset Number The pixel offset at which to start the grid dash array. ≥ 5.0
gridOpacity Number Opacity of axis grid lines.
gridWidth Number Stroke width of axis grid lines.
labels Boolean Boolean flag indicating if axis tick labels should be included by default.
labelAlign String Horizontal text alignment of axis tick labels, overriding the default setting for the axis orientation.
labelAngle Number Angle in degrees of axis tick labels.
labelBaseline String Vertical text baseline of axis tick labels, overriding the default setting for the axis orientation.
labelBound Boolean | Number Boolean flag or pixel tolerance value for removal of labels that exceed the axis range.
labelColor Color Text color of axis tick labels.
labelFlush Boolean | Number Boolean flag or pixel distance threshold value for performing a “flush” layout of axis labels. For an x-axis, flush alignment will left-align the left-most labels (if within the distance threshold from the axis start) and similarly right-align the right-most labels. If true, a pixel tolerance of 1 is used.
labelFlushOffset Number Offset in pixels for flush-adjusted labels (default 0).
labelFont String Font name for axis tick labels.
labelFontSize Number Font size of axis tick labels.
labelFontStyle String Font style of axis tick labels (e.g., normal or italic). ≥ 5.0
labelFontWeight String | Number Font weight of axis tick labels.
labelLimit Number The maximum allowed length in pixels of axis tick labels.
labelOpacity Number Opacity of axis tick labels. ≥ 4.1
labelOverlap Boolean | String The strategy to use for resolving overlap of axis labels. If false, no overlap reduction is attempted. If true or "parity", a strategy of removing every other label is used (this works well for standard linear axes). If "greedy", a linear scan of the labels is performed, removing any labels that overlaps with the last visible label (this often works better for log-scaled axes).
labelSeparation Number The minimum separation that must be between label bounding boxes for them to be considered non-overlapping (default 0). This property is ignored if labelOverlap resolution is not enabled. ≥ 5.0
labelPadding Number Padding in pixels between axis ticks and tick labels.
maxExtent Number The maximum extent in pixels that axis ticks and labels should use. This determines a maximum offset value for axis titles.
minExtent Number The minimum extent in pixels that axis ticks and labels should use. This determines a minimum offset value for axis titles.
ticks Boolean Boolean flag indicating if axis tick marks should be included by default.
tickColor Color Color of axis ticks.
tickDash Number[ ] Stroke dash of axis tick marks (or [] for solid lines). ≥ 5.0
tickDashOffset Number The pixel offset at which to start the tick mark dash array. ≥ 5.0
tickExtra Boolean Boolean flag indicating if an extra axis tick should be added for the initial position of the axis. This flag is useful for styling axes for band scales such that ticks are placed on band boundaries rather in the middle of a band. Use in conjunction with "bandPosition": 1 and an axis "padding" value of 0.
tickOffset Number Position offset in pixels to apply to ticks, labels, and gridlines.
tickOpacity Number Opacity of axis ticks. ≥ 4.1
tickRound Boolean Boolean flag indicating if pixel position values should be rounded to the nearest integer.
tickSize Number Size, or length, in pixels of axis ticks.
tickWidth Number Width in pixels of axis ticks.
titleAlign String Horizontal text alignment of axis titles. One of "left", "center", or "right". If specified, this value overrides automatic alignment based on the titleAnchor value.
titleAnchor String The anchor position for placing axis titles. One of "start", "middle", "end", or null (default, for automatic determination). For example, with an orient of "bottom" these anchor positions map to a left-, center-, or right-aligned title. The anchor point is determined relative to the axis scale range. ≥ 5.0
titleAngle Number Angle in degrees of axis titles.
titleBaseline String Vertical text baseline for axis titles. One of "top", "middle", "bottom", or "alphabetic".
titleColor Color Text color of axis titles.
titleFont String Font name for axis titles.
titleFontSize Number Font size of axis titles.
titleFontStyle String Font style of axis titles (e.g., normal or italic). ≥ 5.0
titleFontWeight String | Number Font weight of axis titles.
titleLimit Number The maximum allowed length in pixels of axis titles.
titleOpacity Number Opacity of axis titles. ≥ 4.1
titlePadding Number Padding in pixels between axis tick labels and titles.
titleX Number X-coordinate of the axis title relative to the axis group.
titleY Number Y-coordinate of the axis title relative to the axis group.

Usage

This example sets the axis label color to dark gray for all axes, and rotates the labels for axes oriented along the bottom of a chart.

{
  "axis": {
    "labelColor": "#ccc"
  },
  "axisBottom": {
    "labelAngle": -90
  }
}

Back to Top

Legend Properties

Properties defining default settings for legends. These properties are defined under the "legend" property within the config object.

Property Type Description
clipHeight Number The height in pixels to clip symbol legend entries and limit their size.
columns Number The number of columns in which to arrange symbol legend entries. A value of 0 or lower indicates a single row with one column per entry.
columnPadding Number The horizontal padding in pixels between symbol legend entries.
cornerRadius Number Corner radius for the full legend.
fillColor Color Background fill color for the full legend.
gradientDirection String The default direction ("horizontal" or "vertical") for gradient legends.
gradientLength Number The length in pixels of the primary axis of a color gradient. This value corresponds to the height of a vertical gradient or the width of a horizontal gradient.
gradientThickness Number The thickness in pixels of the color gradient. This value corresponds to the width of a vertical gradient or the height of a horizontal gradient.
gradientWidth Number Deprecated, use gradientLength instead. If gradientLength is not defined, this value will be used instead.
gradientHeight Number Deprecated, use gradientThickness instead. If gradientThickness is not defined, this value will be used instead.
gradientStrokeColor Color Stroke color for color ramp gradient borders.
gradientStrokeWidth Number Stroke width for color ramp gradient borders.
gradientLabelLimit Number The maximum allowed length in pixels of color ramp gradient labels.
gradientLabelOffset Number Vertical offset in pixels for color ramp gradient labels.
gradientOpacity Number Opacity of color ramp gradient. ≥ 4.1
gridAlign String The alignment to apply to symbol legends rows and columns. The supported string values are all, each (the default), and none. For more information, see the grid layout documentation.
labelAlign String Horizontal text alignment of legend labels.
labelBaseline String Vertical text baseline of legend labels.
labelColor Color Text color of legend labels.
labelFont String Font name of legend labels.
labelFontSize Number Font size in pixels of legend labels.
labelFontStyle String Font style of legend labels (e.g., normal or italic). ≥ 5.0
labelFontWeight String | Number Font weight of legend labels.
labelLimit Number The maximum allowed length in pixels of legend labels.
labelOffset Number Horizontal offset in pixels between legend symbols and labels.
labelOpacity Number Opacity of legend labels. ≥ 4.1
labelOverlap Boolean | String The strategy to use for resolving overlap of labels in gradient legends. If false, no overlap reduction is attempted. If set to true (default) or "parity", a strategy of removing every other label is used. If set to "greedy", a linear scan of the labels is performed, removing any label that overlaps with the last visible label.
labelSeparation Number The minimum separation that must be between label bounding boxes for them to be considered non-overlapping (default 0). This property is ignored if labelOverlap resolution is not enabled. ≥ 5.0
layout Layout An object specifying layout parameters for positioning a collection of legends with the same orient value. ≥ 5.0
legendX Number The pixel x-coordinate of the legend group. Only applied if the orient value is "none". ≥ 5.4
legendY Number The pixel y-coordinate of the legend group. Only applied if the orient value is "none". ≥ 5.4
offset Number Offset in pixels of the legend from the chart body. If specified, this value will override any values specified in the legend layout config.
orient String Default legend orientation (e.g., "right" or "left").
padding Number Padding in pixels between legend border and contents.
rowPadding Number The vertical padding in pixels between symbol legend entries.
strokeColor Color Border stroke color for the full legend.
strokeDash Number[ ] Border stroke dash pattern for the full legend.
strokeWidth Number Border stroke width for the full legend.
symbolBaseFillColor Color Default fill color for legend symbols. Only applied if there is no "fill" scale color encoding for the legend.
symbolBaseStrokeColor Color Default stroke color for legend symbols. Only applied if there is no "fill" scale color encoding for the legend.
symbolDash Number[ ] Stroke dash of symbol outlines (or [] for solid lines). ≥ 5.0
symbolDashOffset Number The pixel offset at which to start the symbol dash array. ≥ 5.0
symbolDirection String The default direction ("horizontal" or "vertical") for symbol legends.
symbolFillColor Color Fill color for legend symbols.
symbolOffset Number Horizontal pixel offset for legend symbols.
symbolOpacity Number Opacity of legend symbols. ≥ 4.1
symbolSize Number Default symbol area size (in pixels2).
symbolStrokeColor Color Stroke color for legend symbols.
symbolStrokeWidth Number Default legend symbol stroke width.
symbolType String Default shape type (such as "circle") for legend symbols.
titleAlign String Horizontal text alignment of legend titles. One of "left", "center", or "right". If specified, this value overrides automatic alignment based on the titleOrient and titleAnchor values.
titleAnchor String The anchor position for placing legend titles. One of "start", "middle", "end", or null (default, for automatic determination). For example, with a titleOrient of "top" these anchor positions map to a left-, center-, or right-aligned title relative to the legend contents. ≥ 5.0
titleBaseline String Vertical text baseline of legend titles. One of "top", "middle", "bottom", or "alphabetic". If specified, this value overrides the automatic baseline based on the titleOrient and titleAnchor values.
titleColor Color Text color of legend titles.
titleFont String Font name of legend titles.
titleFontSize Number Font size in pixels of legend titles.
titleFontStyle String Font style of legend titles (e.g., normal or italic). ≥ 5.0
titleFontWeight String | Number Font weight for legend titles.
titleLimit Number The maximum allowed length in pixels of legend titles.
titleOpacity Number Opacity of legend titles. ≥ 4.1
titleOrient String The orientation of title legends, determining where they are placed relative to legend contents. One of "top" (default), "left", "bottom", or "right". ≥ 5.0
titlePadding Number Padding in pixels between the legend title and entries.

Legend Layout Properties ≥ 5.0

Collections of legends with the same orient value are positioned together, either vertically or horizontally in sequence. The legend layout property enables customization of how legends are organized within a Vega view. The layout property is an object value that may contain both top-level properties that apply to all legends and a set of orient-specific properties for customizing specific legend orientations.

Property Type Description
anchor String An anchor value determining the placement of the legends relative to the nearest axis. One of "start" (default), "middle", or "end". For example, for legends with orient "top", these values respectively correspond to anchoring the legends to the left edge, center, or right edge of the charting area. This property only applies to axes with an orient value of "left", "right", "top", or "bottom".
bounds String The type of bounding box calculation to use for calculating legend extents. One of "flush" (the default, for using legend width and height values only) or "full" (to use the full bounding box, for example including border stroke widths).
center Boolean A boolean flag (default false) indicating if legends should be centered within the respective layout area. For example, given a vertical direction, two legends will share a left edge by default. If center is true, the smaller legends will be centered in the space spanned by all the legends.
direction String The direction in which subsequent legends should be spatially positioned. One of "horizontal" or "vertical".
margin Number Margin, in pixels, to place between consecutive legends with the same orient value.
offset Number Offset, in pixels, of the
legend from the chart body.    

In addition to these top-level properties, the legend layout may include sub-objects (containing the same properties listed above) for any of the legal legend orient values other than "none": "left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right".

Usage

This example gives every legend a 10 pixel padding and a light gray border:

{
  "legend": {
    "padding": 10,
    "legendStrokeColor": "#ccc",
    "legendStrokeWidth": 1
  }
}

This example customizes the layout of legends with orient value "bottom", stacking those legends vertically with 2 pixel margins, anchoring their x-positon to the middle of the chart area, and centering the legends within their layout area:

{
  "legend": {
    "layout": {
      "bottom": {
        "anchor": "middle",
        "direction": "vertical",
        "center": true,
        "margin": 2,
      }
    }
  }
}

Back to Top

Title Properties

Properties defining default settings for titles. These properties are defined under the "title" property within the config object.

Property Type Description
align String Horizontal text alignment of the title. If specified, this value overrides automatic alignment based on the anchor value.
anchor String Title anchor position ("start", "middle", or "end").
angle Number Angle in degrees of the title text.
baseline String Vertical text baseline of the title.
color Color Text color of the title text.
dx Number Horizontal offset added to the title x-coordinate. ≥ 5.2
dy Number Vertical offset added to the title y-coordinate. ≥ 5.2
font String Font name of the title text.
fontSize Number Font size in pixels of the title text.
fontStyle String Font style of the title text (e.g., normal or italic). ≥ 5.0
fontWeight String | Number Font weight for title text.
frame String The reference frame for the anchor position, one of "bounds" (to anchor relative to the full bounding box) or "group" (to anchor relative to the group width or height).
limit Number The maximum allowed length in pixels of legend labels.
offset Number Offset in pixels of the title from the chart body and axes.
orient String Default title orientation ("top", "bottom", "left", or "right").

Usage

This example gives every title a 10 pixel offset and a font size of 18 pixels.

{
  "title": {
    "offset": 10,
    "fontSize": 18
  }
}

Back to Top

Scale Range Properties

Properties defining named range arrays that can be used within scale range definitions (such as {"type": "ordinal", "range": "category"}). These properties are defined under the "range" property in the config object.

Object-valued properties must be legal scale range definitions.

Property Type Description
category Scheme | Color[ ] Default color scheme for categorical data.
diverging Scheme | Color[ ] Default color scheme for diverging quantitative ramps.
heatmap Scheme | Color[ ] Default color scheme for quantitative heatmaps.
ordinal Scheme | Color[ ] Default color scheme for rank-ordered data.
ramp Scheme | Color[ ] Default color scheme for sequential quantitative ramps.
symbol String[ ] Array of symbol names or paths for the default shape palette.

Usage

This example sets new default color palettes.

{
  "range": {
    "category": [
      "#5079a5",
      "#ef8e3b",
      "#dd565c",
      "#79b7b2",
      "#5da052",
      "#ecc853",
      "#ad7aa1",
      "#ef9ba7",
      "#9b7461",
      "#bab0ac"
    ],
    "ordinal": {"scheme": "greens"},
    "ramp": {"scheme": "purples"}
  }
}

Back to Top