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
• Event Properties
• Mark Properties
• Style Properties
• Axis Properties
• Legend Properties
• Title Properties
• Projection Properties
• Scale Range Properties
• Signals

View Properties

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

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.

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.

Axis Accessibility Properties

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

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.

Legend Accessibility Properties

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

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.

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.

Title Accessibility Properties

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

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.

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