Top-Level Chart Configuration

Many aspects of a chart’s appearance can be configured at the top level using the configure_*() methods. These methods and the properties that they set are only valid at the top level of a chart, and can be thought of as a way of setting a chart theme: that is, they set the default styles for the entire chart, and these defaults can be overridden by specific style settings associated with chart elements.

These methods and their arguments will be outlined below:

Chart Configuration

The Chart.configure() method adds a Config instance to the chart, and has the following attributes:

Property Type Description
area MarkConfig Area-Specific Config
autosize anyOf(AutosizeType, 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
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.
axisBand VgAxisConfig Specific axis config for axes with “band” scales.
axisBottom VgAxisConfig Specific axis config for x-axis along the bottom edge of the chart.
axisLeft VgAxisConfig Specific axis config for y-axis along the left edge of the chart.
axisRight VgAxisConfig Specific axis config for y-axis along the right edge of the chart.
axisTop VgAxisConfig Specific axis config for x-axis along the top edge of the chart.
axisX VgAxisConfig X-axis specific config.
axisY VgAxisConfig Y-axis specific config.
background string CSS color property to use as the background of visualization. Default value: none (transparent)
bar BarConfig Bar-Specific Config
circle MarkConfig Circle-Specific Config
countTitle string Default axis and legend title for count fields. Default value: 'Number of Records'.
datasets Datasets A global data store for named datasets. This is a mapping from names to inline datasets. This can be an array of objects or primitive values or a string. Arrays of primitive values are ingested as objects with a data property.
fieldTitle [‘verbal’, ‘functional’, ‘plain’] 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”).
geoshape MarkConfig Geoshape-Specific Config
invalidValues [‘filter’, None] Defines how Vega-Lite should handle invalid values (null and NaN). * If set to "filter" (default), all data items with null values are filtered. * If null, all data items are included. In this case, invalid values will be interpreted as zeroes.
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.
line MarkConfig Line-Specific Config
mark MarkConfig Mark Config
numberFormat string D3 Number format for axis labels and text tables. For example “s” for SI units. Use D3’s number format pattern.
padding Padding 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
point MarkConfig Point-Specific Config
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.
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.
rect MarkConfig Rect-Specific Config
rule MarkConfig Rule-Specific Config
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.
selection SelectionConfig An object hash for defining default properties for each type of selections.
square MarkConfig Square-Specific Config
stack StackOffset Default stack offset for stackable mark.
style StyleConfigIndex An object hash that defines key-value mappings to determine default properties for marks with a given style. The keys represent styles names; the value are valid mark configuration objects.
text TextConfig Text-Specific Config
tick TickConfig Tick-Specific Config
timeFormat string Default datetime format for axis and legend labels. The format can be set directly on each axis and legend. Use D3’s time format pattern. Default value: '%b %d, %Y'.
title VgTitleConfig 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 ViewConfig Default properties for single view plots.

Axis Configuration

Axis configuration defines default settings for axes, and can be set using the Chart.configure_axis() method. Properties defined here are applied to all axes in the figure.

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.

The methods are the following:

  • Chart.configure_axis()
  • Chart.configure_axisBand()
  • Chart.configure_axisBottom()
  • Chart.configure_axisLeft()
  • Chart.configure_axisRight()
  • Chart.configure_axisTop()
  • Chart.configure_axisX()
  • Chart.configure_axisY()

They have the following properties:

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 A boolean flag indicating if the domain (the axis baseline) should be included as part of the axis. Default value: true
domainColor string Color of axis domain line. Default value: (none, using Vega default).
domainWidth number Stroke width of axis domain line Default value: (none, using Vega default).
grid boolean A boolean flag indicating if grid lines should be included as part of the axis Default value: true for continuous scales that are not binned; otherwise, false.
gridColor string Color of gridlines.
gridDash array(number) The offset (in pixels) into which to begin drawing with the grid dash array.
gridOpacity number The stroke opacity of grid (value between [0,1]) Default value: (1 by default)
gridWidth number The grid width, in pixels.
labelAngle number The rotation angle of the axis labels. Default value: -90 for nominal and ordinal fields; 0 otherwise.
labelBound [boolean, number] Indicates if labels should be hidden if they exceed the axis range. If false(the default) no bounds overlap analysis is performed. If true, labels will be hidden if they exceed the axis range by more than 1 pixel. If this property is a number, it specifies the pixel tolerance: the maximum amount by which a label bounding box may exceed the axis range. Default value: false.
labelColor string The color of the tick label, can be in hex color code or regular color name.
labelFlush [boolean, number] Indicates if the first and last axis labels should be aligned flush with the scale range. Flush alignment for a horizontal axis will left-align the first label and right-align the last label. For vertical axes, bottom and top text baselines are applied instead. If this property is a number, it also indicates the number of pixels by which to offset the first and last labels; for example, a value of 2 will flush-align the first and last labels and also push them 2 pixels outward from the center of the axis. The additional adjustment can sometimes help the labels better visually group with corresponding axis ticks. Default value: true for axis of a continuous x-scale. Otherwise, false.
labelFont string The font of the tick label.
labelFontSize number The font size of the label, in pixels.
labelLimit number Maximum allowed pixel width of axis tick labels.
labelOverlap anyOf(boolean, [‘parity’], [‘greedy’]) The strategy to use for resolving overlap of axis labels. If false (the default), no overlap reduction is attempted. If set to true or "parity", a strategy of removing every other label is used (this works well for standard linear axes). If set to "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). Default value: true for non-nominal fields with non-log scales; "greedy" for log scales; otherwise false.
labelPadding number The padding, in pixels, between axis and text labels.
labels boolean A boolean flag indicating if labels should be included as part of the axis. Default value: true.
maxExtent number The maximum extent in pixels that axis ticks and labels should use. This determines a maximum offset value for axis titles. Default value: undefined.
minExtent number The minimum extent in pixels that axis ticks and labels should use. This determines a minimum offset value for axis titles. Default value: 30 for y-axis; undefined for x-axis.
shortTimeLabels boolean Whether month names and weekday names should be abbreviated. Default value: false
tickColor string The color of the axis’s tick.
tickRound boolean Boolean flag indicating if pixel position values should be rounded to the nearest integer.
tickSize number The size in pixels of axis ticks.
tickWidth number The width, in pixels, of ticks.
ticks boolean Boolean value that determines whether the axis should include 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 string Color of the title, can be in hex color code or regular color name.
titleFont string Font of the title. (e.g., "Helvetica Neue").
titleFontSize number Font size of the title.
titleFontWeight FontWeight Font weight of the title. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, …, 900 where "normal" = 400 and "bold" = 700).
titleLimit number Maximum allowed pixel width of axis titles.
titleMaxLength number Max length for axis title if the title is automatically generated from the field’s description.
titlePadding number The padding, in pixels, between title and axis.
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.

Legend Configuration

Legend properties can be configured using Chart.configure_legend(), which has the following properties:

Property Type Description
cornerRadius number Corner radius for the full legend.
entryPadding number Padding (in pixels) between legend entries in a symbol legend.
fillColor string Background fill color for the full legend.
gradientHeight number The height of the gradient, in pixels.
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.
gradientStrokeColor string The color of the gradient stroke, can be in hex color code or regular color name.
gradientStrokeWidth number The width of the gradient stroke, in pixels.
gradientWidth number The width of the gradient, in pixels.
labelAlign string The alignment of the legend label, can be left, middle or right.
labelBaseline string The position of the baseline of legend label, can be top, middle or bottom.
labelColor string The color of the legend label, can be in hex color code or regular color name.
labelFont string The font of the legend label.
labelFontSize number The font size of legend label. Default value: 10.
labelLimit number Maximum allowed pixel width of axis tick labels.
labelOffset number The offset of the legend label.
offset number The offset, in pixels, by which to displace the legend from the edge of the enclosing group or data rectangle. Default value: 0
orient LegendOrient The orientation of the legend, which determines how the legend is positioned within the scene. One of “left”, “right”, “top-left”, “top-right”, “bottom-left”, “bottom-right”, “none”. Default value: "right"
padding number The padding, in pixels, between the legend and axis.
shortTimeLabels boolean Whether month names and weekday names should be abbreviated. Default value: false
strokeColor string Border stroke color for the full legend.
strokeDash array(number) Border stroke dash pattern for the full legend.
strokeWidth number Border stroke width for the full legend.
symbolColor string The color of the legend symbol,
symbolSize number The size of the legend symbol, in pixels.
symbolStrokeWidth number The width of the symbol’s stroke.
symbolType string Default shape type (such as “circle”) for legend symbols.
titleAlign string Horizontal text alignment for legend titles.
titleBaseline string Vertical text baseline for legend titles.
titleColor string The color of the legend title, can be in hex color code or regular color name.
titleFont string The font of the legend title.
titleFontSize number The font size of the legend title.
titleFontWeight FontWeight The font weight of the legend title. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, …, 900 where "normal" = 400 and "bold" = 700).
titleLimit number Maximum allowed pixel width of axis titles.
titlePadding number The padding, in pixels, between title and legend.

Mark and Mark Style Configuration

The mark configuration can be set using the Chart.configure_mark() method, which sets the default properties for all marks in the chart. In addition, the config object also provides mark-specific configuration using the mark type (e.g. Chart.configure_area()) for defining default properties for each mark.

For general configuration of all mark types, use:

  • Chart.configure_mark()

For configurations specific to particular mark types, use:

  • Chart.configure_area()
  • Chart.configure_bar()
  • Chart.configure_circle()
  • Chart.configure_geoshape()
  • Chart.configure_line()
  • Chart.configure_point()
  • Chart.configure_rect()
  • Chart.configure_rule()
  • Chart.configure_square()
  • Chart.configure_text()
  • Chart.configure_tick()

Each of the above methods accepts the following properties:

Property Type Description
align HorizontalAlign The horizontal alignment of the text. One of "left", "right", "center".
angle number The rotation angle of the text, in degrees.
baseline VerticalAlign The vertical alignment of the text. One of "top", "middle", "bottom". Default value: "middle"
color string  
cursor [‘auto’, ‘default’, ‘none’, ‘context-menu’, ‘help’, ‘pointer’, ‘progress’, ‘wait’, ‘cell’, ‘crosshair’, ‘text’, ‘vertical-text’, ‘alias’, ‘copy’, ‘move’, ‘no-drop’, ‘not-allowed’, ‘e-resize’, ‘n-resize’, ‘ne-resize’, ‘nw-resize’, ‘s-resize’, ‘se-resize’, ‘sw-resize’, ‘w-resize’, ‘ew-resize’, ‘ns-resize’, ‘nesw-resize’, ‘nwse-resize’, ‘col-resize’, ‘row-resize’, ‘all-scroll’, ‘zoom-in’, ‘zoom-out’, ‘grab’, ‘grabbing’] The mouse cursor used over the mark. Any valid CSS cursor type can be used.
dx number The horizontal offset, in pixels, between the text label and its anchor point. The offset is applied after rotation by the angle property.
dy number The vertical offset, in pixels, between the text label and its anchor point. The offset is applied after rotation by the angle property.
fill string Default Fill Color. This has higher precedence than config.color Default value: (None)
fillOpacity number The fill opacity (value between [0,1]). Default value: 1
filled boolean Whether the mark’s color should be used as fill color instead of stroke color. Default value: true for all marks except point and false for point. Applicable for: bar, point, circle, square, and area marks. Note: This property cannot be used in a style config.
font string The typeface to set the text in (e.g., "Helvetica Neue").
fontSize number The font size, in pixels.
fontStyle FontStyle The font style (e.g., "italic").
fontWeight FontWeight The font weight. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, …, 900 where "normal" = 400 and "bold" = 700).
href string A URL to load upon mouse click. If defined, the mark acts as a hyperlink.
interpolate Interpolate The line interpolation method to use for line and area marks. One of the following: * "linear": piecewise linear segments, as in a polyline. * "linear-closed": close the linear segments to form a polygon. * "step": alternate between horizontal and vertical segments, as in a step function. * "step-before": alternate between vertical and horizontal segments, as in a step function. * "step-after": alternate between horizontal and vertical segments, as in a step function. * "basis": a B-spline, with control point duplication on the ends. * "basis-open": an open B-spline; may not intersect the start or end. * "basis-closed": a closed B-spline, as in a loop. * "cardinal": a Cardinal spline, with control point duplication on the ends. * "cardinal-open": an open Cardinal spline; may not intersect the start or end, but will intersect other control points. * "cardinal-closed": a closed Cardinal spline, as in a loop. * "bundle": equivalent to basis, except the tension parameter is used to straighten the spline. * "monotone": cubic interpolation that preserves monotonicity in y.
limit number The maximum length of the text mark in pixels (default 0, indicating no limit). The text value will be automatically truncated if the rendered size exceeds the limit.
opacity number The overall opacity (value between [0,1]). Default value: 0.7 for non-aggregate plots with point, tick, circle, or square marks or layered bar charts and 1 otherwise.
orient Orient The orientation of a non-stacked bar, tick, area, and line charts. The value is either horizontal (default) or vertical. * For bar, rule and tick, this determines whether the size of the bar and tick should be applied to x or y dimension. * For area, this property determines the orient property of the Vega output. * For line, this property determines the sort order of the points in the line if config.sortLineBy is not specified. For stacked charts, this is always determined by the orientation of the stack; therefore explicitly specified value will be ignored.
radius number Polar coordinate radial offset, in pixels, of the text label from the origin determined by the x and y properties.
shape string The default symbol shape to use. One of: "circle" (default), "square", "cross", "diamond", "triangle-up", or "triangle-down", or a custom SVG path. Default value: "circle"
size number The pixel area each the point/circle/square. For example: in the case of circles, the radius is determined in part by the square root of the size value. Default value: 30
stroke string Default Stroke Color. This has higher precedence than config.color Default value: (None)
strokeDash array(number) An array of alternating stroke, space lengths for creating dashed or dotted lines.
strokeDashOffset number The offset (in pixels) into which to begin drawing with the stroke dash array.
strokeOpacity number The stroke opacity (value between [0,1]). Default value: 1
strokeWidth number The stroke width, in pixels.
tension number Depending on the interpolation type, sets the tension parameter (for line and area marks).
text string Placeholder text if the text channel is not specified
theta number Polar coordinate angle, in radians, of the text label from the origin determined by the x and y properties. Values for theta follow the same convention of arc mark startAngle and endAngle properties: angles are measured in radians, with 0 indicating “north”.

In addition to the default mark properties above, default values can be further customized using named styles defined as keyword arguments to the Chart.configure_style() method. Styles can then be invoked by including a style property within a mark definition object.

Scale Configuration

Scales can be configured using Chart.configure_scale(), which has the following properties:

Property Type Description
bandPaddingInner number Default inner padding for x and y band-ordinal scales. Default value: 0.1
bandPaddingOuter number Default outer padding for x and y band-ordinal scales. If not specified, by default, band scale’s paddingOuter is paddingInner/2.
clamp boolean If true, values that exceed the data domain are clamped to either the minimum or maximum range value
continuousPadding number Default padding for continuous scales. Default: 5 for continuous x-scale of a vertical bar and continuous y-scale of a horizontal bar.; 0 otherwise.
maxBandSize number The default max value for mapping quantitative fields to bar’s size/bandSize. If undefined (default), we will use the scale’s rangeStep - 1.
maxFontSize number The default max value for mapping quantitative fields to text’s size/fontSize. Default value: 40
maxOpacity number Default max opacity for mapping a field to opacity. Default value: 0.8
maxSize number Default max value for point size scale.
maxStrokeWidth number Default max strokeWidth for strokeWidth (or rule/line’s size) scale. Default value: 4
minBandSize number The default min value for mapping quantitative fields to bar and tick’s size/bandSize scale with zero=false. Default value: 2
minFontSize number The default min value for mapping quantitative fields to tick’s size/fontSize scale with zero=false Default value: 8
minOpacity number Default minimum opacity for mapping a field to opacity. Default value: 0.3
minSize number Default minimum value for point size scale with zero=false. Default value: 9
minStrokeWidth number Default minimum strokeWidth for strokeWidth (or rule/line’s size) scale with zero=false. Default value: 1
pointPadding number Default outer padding for x and y point-ordinal scales. Default value: 0.5
rangeStep [number, null] Default range step for band and point scales of (1) the y channel and (2) the x channel when the mark is not text. Default value: 21
round boolean If true, rounds numeric output values to integers. This can be helpful for snapping to the pixel grid. (Only available for x, y, and size scales.)
textXRangeStep number Default range step for x band and point scales of text marks. Default value: 90
useUnaggregatedDomain boolean Use the source data range before aggregation as scale domain instead of aggregated data for aggregate axis. This is equivalent to setting domain to "unaggregate" for aggregated quantitative fields by default. This property only works with aggregate functions that produce values within the raw data domain ("mean", "average", "median", "q1", "q3", "min", "max"). For other aggregations that produce values outside of the raw data domain (e.g. "count", "sum"), this property is ignored. Default value: false

Scale Range Configuration

Scale ranges can be configured using Chart.configure_range(), which has the following properties:

Property Type Description
category anyOf(array(string), VgScheme) Default range for nominal (categorical) fields.
diverging anyOf(array(string), VgScheme) Default range for diverging quantitative fields.
heatmap anyOf(array(string), VgScheme) Default range for quantitative heatmaps.
ordinal anyOf(array(string), VgScheme) Default range for ordinal fields.
ramp anyOf(array(string), VgScheme) Default range for quantitative and temporal fields.
symbol array(string) Default range palette for the shape channel.

Projection Configuration

Chart.configure_projection()

Property Type Description
center array(number) Sets the projection’s center to the specified center, a two-element array of longitude and latitude in degrees. Default value: [0, 0]
clipAngle number Sets the projection’s clipping circle radius to the specified angle in degrees. If null, switches to antimeridian cutting rather than small-circle clipping.
clipExtent array(array(number)) Sets the projection’s viewport clip extent to the specified bounds in pixels. The extent bounds are specified as an array [[x0, y0], [x1, y1]], where x0 is the left-side of the viewport, y0 is the top, x1 is the right and y1 is the bottom. If null, no viewport clipping is performed.
coefficient number  
distance number  
fraction number  
lobes number  
parallel number  
precision dict Sets the threshold for the projection’s adaptive resampling to the specified value in pixels. This value corresponds to the Douglas–Peucker distance. If precision is not specified, returns the projection’s current resampling precision which defaults to √0.5 0.70710….
radius number  
ratio number  
rotate array(number) Sets the projection’s three-axis rotation to the specified angles, which must be a two- or three-element array of numbers [lambda, phi, gamma] specifying the rotation angles in degrees about each spherical axis. (These correspond to yaw, pitch and roll.) Default value: [0, 0, 0]
spacing number  
tilt number  
type ProjectionType The cartographic projection to use. This value is case-insensitive, for example "albers" and "Albers" indicate the same projection type. You can find all valid projection types in the documentation. Default value: mercator

Selection Configuration

Chart.configure_selection()

Property Type Description
interval IntervalSelectionConfig The default definition for an ``interval` <selection.html#type>`_ selection. All properties and transformations for an interval selection definition (except type) may be specified here. For instance, setting interval to {"translate": false} disables the ability to move interval selections by default.
multi MultiSelectionConfig The default definition for a ``multi` <selection.html#type>`_ selection. All properties and transformations for a multi selection definition (except type) may be specified here. For instance, setting multi to {"toggle": "event.altKey"} adds additional values to multi selections when clicking with the alt-key pressed by default.
single SingleSelectionConfig The default definition for a ``single` <selection.html#type>`_ selection. All properties and transformations for a single selection definition (except type) may be specified here. For instance, setting single to {"on": "dblclick"} populates single selections on double-click by default.

View Configuration

Chart.configure_view()

Property Type Description
clip boolean Whether the view should be clipped.
fill string The fill color. Default value: (none)
fillOpacity number The fill opacity (value between [0,1]). Default value: (none)
height number The default height of the single plot or each plot in a trellis plot when the visualization has a continuous (non-ordinal) y-scale with rangeStep = null. Default value: 200
stroke string The stroke color. Default value: (none)
strokeDash array(number) An array of alternating stroke, space lengths for creating dashed or dotted lines. Default value: (none)
strokeDashOffset number The offset (in pixels) into which to begin drawing with the stroke dash array. Default value: (none)
strokeOpacity number The stroke opacity (value between [0,1]). Default value: (none)
strokeWidth number The stroke width, in pixels. Default value: (none)
width number The default width of the single plot or each plot in a trellis plot when the visualization has a continuous (non-ordinal) x-scale or ordinal x-scale with rangeStep = null. Default value: 200