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 | Signal Default automatic sizing setting. Valid string values are "pad", "fit" or "none". See the autosize documentation for more. Signal support available in versions ≥ 5.10.
background Color | Signal Background color of the view component, or null for transparent. Signal support available in versions ≥ 5.10.
description String The default text description for visualizations. The description determines the aria-label attribute for the container element of a Vega view. ≥ 5.10
padding Number | Object | Signal The padding in pixels to add around the visualization. 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}. Signal support available in versions ≥ 5.10.
width Number | Signal The width in pixels of the data rectangle. ≥ 5.10
height Number | Signal The height in pixels of the data rectangle. ≥ 5.10
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".
locale Object Locale definitions for string parsing and formatting of number and date values. The locale object should contain number and/or time properties with locale definitions. Locale definitions provided in the config block may be overridden by the View constructor locale option. ≥ 5.12
lineBreak String | Signal A delimiter, such as a newline character, upon which to break text strings into multiple lines. This property provides a global default for text marks, which is overridden by mark or style config settings, and by the lineBreak mark encoding channel. If signal-valued, either string or regular expression (regexp) values are valid. ≥ 5.10

Usage

Set default view background and chart plotting area background colors:

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

Set the number and time format locale to German:

{
  "locale": {
    "number": {
      "decimal": ",",
      "thousands": ".",
      "grouping": [3],
      "currency": ["", " €"]
    },
    "time": {
      "dateTime": "%A, der %e. %B %Y, %X",
      "date": "%d.%m.%Y",
      "time": "%H:%M:%S",
      "periods": ["AM", "PM"],
      "days": ["Sonntag", "Montag", "Dienstag", "Mittwoch", "Donnerstag", "Freitag", "Samstag"],
      "shortDays": ["So", "Mo", "Di", "Mi", "Do", "Fr", "Sa"],
      "months": ["Januar", "Februar", "März", "April", "Mai", "Juni", "Juli", "August", "September", "Oktober", "November", "Dezember"],
      "shortMonths": [ "Jan", "Feb", "Mrz", "Apr", "Mai", "Jun", "Jul", "Aug", "Sep", "Okt", "Nov", "Dez"]
    }
  }
}

Back to Top

Event Properties

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

Property Type Description
bind String Configuration control for binding input DOM elements to signals. The available options are "any" (default, all bindings are allowed), "container" (use only the view container DOM element for all bindings, suppressing per-binding selectors), and "none" (suppresses all input bindings). ≥ 5.5
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.
globalCursor Boolean Configuration control for dynamic cursor setting. If false (default), the cursor is set for the Vega View element only. If true, the cursor is set globally for the entire document body. The default value of false avoids performance issues in browsers that recalculate styles in response to cursor changes. ≥ 5.13
selector Boolean | String[ ] Configuration control for event listeners for external sources specified using a CSS selector. If a boolean value, true (default) permits selector event listeners, false disallows all selector events. If a string array, the entries specify a list of event types (such as "mousemove" or "wheel") to allow. ≥ 5.5
timer Boolean Configuration control for event listeners for a "timer" source. One of true (default) to permit timer event listeners, or false to disallow timer events. ≥ 5.5
view Boolean | String[ ] Configuration control for event listeners for the Vega "view" source. If a boolean value, true (default) permits view event listeners, false disallows all view events. If a string array, the entries specify a list of event types (such as "mousemove" or "wheel") to allow. ≥ 5.5
window Boolean | String[ ] Configuration control for event listeners for the browser "window" source. If a boolean value, true (default) permits window event listeners, false disallows all window events. If a string array, the entries specify a list of event types (such as "mousemove" or "wheel") to allow. ≥ 5.5

Usage

To disable event listeners on external DOM elements specified by a CSS selector and permit only mousemove and mouseup events on the browser window object:

"events": {
  "selector": false,
  "window": ["mousemove", "mouseup"]
}

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.
domainCap String The stroke cap for the axis domain line. One of "butt" (default), "round" or "square". ≥ 5.11
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.
gridCap String The stroke cap for axis grid lines. One of "butt" (default), "round" or "square". ≥ 5.11
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.
labelLineHeight Number Line height in pixels for multi-line label text. ≥ 5.10
labelOffset Number Position offset in pixels to apply to labels, in addition to tickOffset. ≥ 5.10
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.
tickBand String Indicates the type of tick style to use in conjunction with band scales. One of "center" (default) to center ticks in the middle of the band interval, or "extent" to place ticks at band extents (interval boundaries). If specified, this property may override the settings of bandPosition, tickExtra, and tickOffset. ≥ 5.8
tickCap String The stroke cap for axis tick marks. One of "butt" (default), "round" or "square". ≥ 5.11
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.
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.
titleLineHeight Number Line height in pixels for multi-line title text. ≥ 5.7
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.
translate Number Coordinate space translation offset for axis layout. By default, axes are translated by a 0.5 pixel offset for both the x and y coordinates, in order to align stroked lines with the pixel grid. However, for vector graphics output these pixel-specific adjustments may be undesirable, in which case translate can be changed (for example, to zero). ≥ 5.8
zindex Number The integer z-index indicating the layering of the axis group relative to other axis, mark, and legend groups. With a value of 0 axes and grid lines are drawn behind any marks defined in the same specification level. Higher values (1) cause axes and grid lines to be drawn on top of marks. ≥ 5.11

Axis Accessibility Properties

Accessibility properties are used to determine ARIA (Accessible Rich Internet Applications) attributes when using Vega to render SVG output.

Property Type Description
aria Boolean A boolean flag (default true) indicating if ARIA attributes should be included (SVG output only). If false, the “aria-hidden” attribute will be set on the output SVG group, removing the axis from the ARIA accessibility tree. ≥ 5.11
description String A text description of this axis for ARIA accessibility (SVG output only). If the aria property is true, for SVG output the “aria-label” attribute will be set to this description. If the description is unspecified it will be automatically generated. ≥ 5.11

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.
symbolLimit Number The maximum number of allowed entries for a symbol legend. If the number of entries exceeds the limit, entries will be dropped and replaced with an ellipsis. ≥ 5.7
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.
tickCount Number | String | Object The desired number of tick values for quantitative legends. For scales of type time or utc, the tick count can instead be a time interval specifier. Legal string values are "millisecond", "second", "minute", "hour", "day", "week", "month", and "year". Alternatively, an object-valued interval specifier of the form {"interval": "month", "step": 3} includes a desired number of interval steps. Here, ticks are generated for each quarter (Jan, Apr, Jul, Oct) boundary. ≥ 5.7
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. 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.
titleLineHeight Number Line height in pixels for multi-line title text. ≥ 5.7
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.
zindex Number The integer z-index indicating the layering of the legend group relative to other axis, mark, and legend groups. ≥ 5.11

Legend Accessibility Properties

Accessibility properties are used to determine ARIA (Accessible Rich Internet Applications) attributes when using Vega to render SVG output.

Property Type Description
aria Boolean A boolean flag (default true) indicating if ARIA attributes should be included (SVG output only). If false, the “aria-hidden” attribute will be set on the output SVG group, removing the legend from the ARIA accessibility tree. ≥ 5.11
description String A text description of this legend for ARIA accessibility (SVG output only). If the aria property is true, for SVG output the “aria-label” attribute will be set to this description. If the description is unspecified it will be automatically generated. ≥ 5.11

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

Note: The default configuration includes legend layout entries for "left" and "right" orientations. If you add custom layout parameters at the top-level, these will not override more specific configurations. If you want to modify the layout of "left"- or "right"-oriented legends, use a specific sub-object targeting those orientations.

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 and subtitle. If specified, this value overrides automatic alignment based on the anchor value.
anchor String Title and subtitle anchor position ("start", "middle", or "end").
angle Number Angle in degrees of the title and subtitle text.
baseline String Vertical text baseline of the title and subtitle.
color Color Text color of the title text.
dx Number Horizontal offset added to the title and subtitle x-coordinate. ≥ 5.2
dy Number Vertical offset added to the title and subtitle 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 title and subtitle text.
lineHeight Number Line height in pixels for multi-line title text. ≥ 5.7
offset Number Offset in pixels of the title from the chart body and axes.
orient String Default title orientation ("top", "bottom", "left", or "right").
subtitleColor Color Text color of the subtitle text. ≥ 5.7
subtitleFont String Font name of the subtitle text. ≥ 5.7
subtitleFontSize Number Font size in pixels of the subtitle text. ≥ 5.7
subtitleFontStyle String Font style of the subtitle text (e.g., normal or italic). ≥ 5.7
subtitleFontWeight String | Number Font weight for subtitle text. ≥ 5.7
subtitleLineHeight Number Line height in pixels for multi-line subtitle text. ≥ 5.7
subtitlePadding Number Padding in pixels between title and subtitle text. ≥ 5.7
zindex Number The integer z-index indicating the layering of the title group relative to other axis, mark, and legend groups. ≥ 5.11

Title Accessibility Properties

Accessibility properties are used to determine ARIA (Accessible Rich Internet Applications) attributes when using Vega to render SVG output.

Property Type Description
aria Boolean A boolean flag (default true) indicating if ARIA attributes should be included (SVG output only). If false, the “aria-hidden” attribute will be set on the output SVG group, removing the title from the ARIA accessibility tree. ≥ 5.11

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

Projection Properties

Default properties to apply to cartographic projections, if not explicitly included in the input JSON specification. Any legal projection property may be included. These properties are defined under the "projection" property in the config object. A common use for this property is to set a default projection type.

Usage

This example sets the default projection type to be an "equalEarth" projection:

{
  "projection": {
    "type": "equalEarth"
  }
}

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

Signal Definitions ≥ 5.5

Configuration files may also contain signal definitions for the top-level scope of a Vega specification. The syntax is identical to standard signal definitions: an array of named signal objects. Adding signal definitions to a configuration can be useful for defining style variables (colors, font sizes, etc.) that may be used elsewhere within either the config or a spec itself. Signals directly defined within a specification itself take precedence over those defined in the configuration.

Usage

To enable dynamic scaling of font sizes, one can define a signal that for a font size scale factor, then define other config entries relative to this value:

{
  "signals": [
    {"name": "fontSizeScale", "value": 1}
  ],
  "text": {
    "fontSize": {"signal": "11 * fontSizeScale"}
  }
}

Back to Top