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:

{
  "$schema": "https://vega.github.io/schema/vega/v3.0.json",
  "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.

Defaults for fill or stroke color will be applied only if neither "fill" nor "stroke" are defined in the Vega spec.

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.
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).
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.
labelAngle Number Angle in degrees of axis tick labels.
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.
labelLimit Number The maximum allowed length in pixels of axis tick labels.
labelPadding Number Padding in pixels betweem 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.
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 "bandPostion": 1 and an axis "padding" value of 0.
tickOffset Number Position offset in pixels to apply to ticks, labels, and gridlines.
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.
titleAngle Number Angle in degrees of axis titles.
titleBaseline String Vertical text baseline for axis titles.
titleColor Color Text color of axis titles.
titleFont String Font name for axis titles.
titleFontSize Number Font size of axis titles.
titleFontWeight String Font weight of axis titles.
titleLimit Number The maximum allowed length in pixels of axis titles.
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
cornerRadius Number Corner radius for the full legend.
entryPadding Number Padding in pixels between legend entries in a symbol legend.
fillColor Color Background fill color for the full legend.
gradientWidth Number Width in pixels of color ramp gradients.
gradientHeight Number Height in pixels of color ramp gradients.
gradientStrokeColor Color Stroke color for color ramp gradient borders.
gradientStrokeWidth Number Stroke width for color ramp gradient borders.
gradientLabelBaseline String Text baseline for color ramp gradient labels.
gradientLabelLimit Number The maximum allowed length in pixels of color ramp gradient labels.
gradientLabelOffset Number Vertical offset in pixels for color ramp gradient labels.
labelAlign String Horizontal text alignment for legend labels.
labelBaseline String Vertical text baseline for legend labels.
labelColor Color Text color for legend labels.
labelFont String Font name for legend labels.
labelFontSize Number Font size in pixels for legend labels.
labelLimit Number The maximum allowed length in pixels of legend labels.
labelOffset Number Horizontal offset in pixels between legend symbols and labels.
offset Number Offset in pixels of the legend from the chart body.
orient String Default legend orientation (e.g., "right" or "left").
padding Number Padding in pixels between legend border and contents.
titleAlign String Horizontal text alignment for legend titles.
titleBaseline String Vertical text baseline for legend titles.
titleColor Color Text color for legend titles.
titleFont String Font name for legend titles.
titleFontSize Number Font size in pixels for legend titles.
titleFontWeight String Font weight for legend titles.
titleLimit Number The maximum allowed length in pixels of legend titles.
titlePadding Number Padding in pixels between the legend title and 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.
symbolType String Default shape type (such as "circle") for legend symbols.
symbolSize Number Default symbol area size (in pixels2).
symbolFillColor Color Default fill color for legend symbols. Only applied if there is no "fill" scale color encoding for the legend.
symbolStrokeColor Color Default stroke color for legend symbols. Only applied if there is no "fill" scale color encoding for the legend.
symbolStrokeWidth Number Default legend symbol stroke width.

Usage

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

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

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
anchor String Title anchor position ("start", "middle", or "end").
angle Number Angle in degrees of title text.
baseline String Vertical text baseline for title text.
color Color Text color for title text.
font String Font name for title text.
fontSize Number Font size in pixels for title text.
fontWeight String Font weight for title text.
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