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:

For more discussion of approaches to chart customization, see Customizing Visualizations.

Chart Configuration

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

Property Type Description
area AreaConfig Area-Specific Config
autosize anyOf(AutosizeType, AutoSizeParams)

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.

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 AxisConfig Specific axis config for axes with “band” scales.
axisBottom AxisConfig Specific axis config for x-axis along the bottom edge of the chart.
axisLeft AxisConfig Specific axis config for y-axis along the left edge of the chart.
axisRight AxisConfig Specific axis config for y-axis along the right edge of the chart.
axisTop AxisConfig Specific axis config for x-axis along the top edge of the chart.
axisX AxisConfig X-axis specific config.
axisY AxisConfig Y-axis specific config.
background Color

CSS color property to use as the background of the entire view.

Default value: "white"

bar RectConfig Bar-Specific Config
boxplot BoxPlotConfig Box Config
circle MarkConfig Circle-Specific Config
concat CompositionConfig Default configuration for all concatenation view composition operators (concat, hconcat, and vconcat)
countTitle string

Default axis and legend title for count fields.

Default value: 'Count of Records.

errorband ErrorBandConfig ErrorBand Config
errorbar ErrorBarConfig ErrorBar Config
facet CompositionConfig Default configuration for the facet view composition operator
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
header HeaderConfig

Header configuration, which determines default properties for all headers.

For a full list of header configuration options, please see the corresponding section of in the header documentation.

headerColumn HeaderConfig

Header configuration, which determines default properties for column headers.

For a full list of header configuration options, please see the corresponding section of in the header documentation.

headerFacet HeaderConfig

Header configuration, which determines default properties for non-row/column facet headers.

For a full list of header configuration options, please see the corresponding section of in the header documentation.

headerRow HeaderConfig

Header configuration, which determines default properties for row headers.

For a full list of header configuration options, please see the corresponding section of in the header documentation.

image RectConfig Image-specific Config
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 LineConfig Line-Specific Config
mark MarkConfig Mark Config
numberFormat string D3 Number format for guide labels and text marks. 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 RectConfig Rect-Specific Config
repeat CompositionConfig Default configuration for the repeat view composition operator
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
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 values have to be valid mark configuration objects.
text MarkConfig Text-Specific Config
tick TickConfig Tick-Specific Config
timeFormat string

Default time format for raw time values (without time units) in text marks, legend labels and header labels.

Default value: "%b %d, %Y" Note: Axes automatically determine format each label automatically so this config would not affect axes.

title TitleConfig 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.
trail LineConfig Trail-Specific Config
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:

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.

Default value: 0.5

domain boolean

A boolean flag indicating if the domain (the axis baseline) should be included as part of the axis.

Default value: true

domainColor anyOf(null, Color)

Color of axis domain line.

Default value: "gray".

domainDash array(number) An array of alternating [stroke, space] lengths for dashed domain lines.
domainDashOffset number The pixel offset at which to start drawing with the domain dash array.
domainOpacity number Opacity of the axis domain line.
domainWidth number

Stroke width of axis domain line

Default value: 1

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 anyOf(anyOf(null, Color), ConditionalAxisColor)  
gridDash anyOf(array(number), ConditionalAxisNumberArray)  
gridDashOffset anyOf(number, ConditionalAxisNumber)  
gridOpacity anyOf(number, ConditionalAxisNumber)  
gridWidth anyOf(number, ConditionalAxisNumber)  
labelAlign anyOf(Align, ConditionalAxisNumber)  
labelAngle number

The rotation angle of the axis labels.

Default value: -90 for nominal and ordinal fields; 0 otherwise.

labelBaseline anyOf(TextBaseline, ConditionalAxisLabelBaseline)  
labelBound [number, boolean]

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 anyOf(anyOf(null, Color), ConditionalAxisColor)  
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.

labelFlushOffset number

Indicates the number of pixels by which to offset flush-adjusted labels. For example, a value of 2 will push flush-adjusted labels 2 pixels outward from the center of the axis. Offsets can help the labels better visually group with corresponding axis ticks.

Default value: 0.

labelFont anyOf(string, ConditionalAxisString)  
labelFontSize anyOf(number, ConditionalAxisNumber)  
labelFontStyle anyOf(FontStyle, ConditionalAxisLabelFontStyle)  
labelFontWeight anyOf(FontWeight, ConditionalAxisLabelFontWeight)  
labelLimit number

Maximum allowed pixel width of axis tick labels.

Default value: 180

labelOpacity anyOf(number, ConditionalAxisNumber)  
labelOverlap LabelOverlap

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.

Default value: 2

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

orient AxisOrient

The orientation of the axis. One of "top", "bottom", "left" or "right". The orientation can be used to further specialize the axis type (e.g., a y-axis oriented towards the right edge of the chart).

Default value: "bottom" for x-axes and "left" for y-axes.

tickBand [‘center’, ‘extent’] For band scales, indicates if ticks and grid lines should be placed at the center of a band (default) or at the band extents to indicate intervals.
tickColor anyOf(anyOf(null, Color), ConditionalAxisColor)  
tickDash anyOf(array(number), ConditionalAxisNumberArray)  
tickDashOffset anyOf(number, ConditionalAxisNumber)  
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 anyOf(number, ConditionalAxisNumber)  
tickRound boolean

Boolean flag indicating if pixel position values should be rounded to the nearest integer.

Default value: true

tickSize number

The size in pixels of axis ticks.

Default value: 5

tickWidth anyOf(number, ConditionalAxisNumber)  
ticks boolean

Boolean value that determines whether the axis should include ticks.

Default value: true

title null Set to null to disable title for the axis, legend, or header.
titleAlign Align Horizontal text alignment of axis titles.
titleAnchor TitleAnchor Text anchor position for placing axis titles.
titleAngle number Angle in degrees of axis titles.
titleBaseline TextBaseline Vertical text baseline for axis titles.
titleColor anyOf(null, Color) 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.
titleFontStyle FontStyle Font style 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.
titleLineHeight number Line height in pixels for multi-line title text.
titleOpacity number Opacity of the axis title.
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.
translate number Translation offset in pixels applied to the axis group mark x and y. If specified, overrides the default behavior of a 0.5 offset to pixel-align stroked lines.

Header Configuration

The Chart.configure_header() method allows configuration of facet headers, including the font, color, size, and position of the title and labels. Here is an example:

import altair as alt
from vega_datasets import data

source = data.cars.url

chart = alt.Chart(source).mark_point().encode(
    x='Horsepower:Q',
    y='Miles_per_Gallon:Q',
    color='Origin:N',
    column='Origin:N'
).properties(
    width=180,
    height=180
)

chart.configure_header(
    titleColor='green',
    titleFontSize=14,
    labelColor='red',
    labelFontSize=14
)
Property Type Description
format string

The text formatting pattern for labels of guides (axes, legends, headers) and text marks.

See the format documentation for more examples.

Default value: Derived from numberFormat config for number format and from timeFormat config for time format.

formatType [‘number’, ‘time’]

The format type for labels ("number" or "time").

Default value:

  • "time" for temporal fields and ordinal and nomimal fields with timeUnit.
  • "number" for quantitative fields as well as ordinal and nomimal fields without timeUnit.
labelAlign Align Horizontal text alignment of header labels. One of "left", "center", or "right".
labelAnchor TitleAnchor The anchor position for placing the labels. One of "start", "middle", or "end". For example, with a label orientation of top these anchor positions map to a left-, center-, or right-aligned label.
labelAngle number

The rotation angle of the header labels.

Default value: 0 for column header, -90 for row header.

labelColor Color The color of the header label, can be in hex color code or regular color name.
labelExpr string

Vega expression for customizing labels.

Note: The label text and value can be assessed via the label and value properties of the header’s backing datum object.

labelFont string The font of the header label.
labelFontSize number The font size of the header label, in pixels.
labelFontStyle FontStyle The font style of the header label.
labelLimit number

The maximum length of the header label in pixels. The text value will be automatically truncated if the rendered size exceeds the limit.

Default value: 0, indicating no limit

labelOrient Orient The orientation of the header label. One of "top", "bottom", "left" or "right".
labelPadding number

The padding, in pixel, between facet header’s label and the plot.

Default value: 10

labels boolean

A boolean flag indicating if labels should be included as part of the header.

Default value: true.

title null Set to null to disable title for the axis, legend, or header.
titleAlign Align Horizontal text alignment (to the anchor) of header titles.
titleAnchor TitleAnchor The anchor position for placing the title. One of "start", "middle", or "end". For example, with an orientation of top these anchor positions map to a left-, center-, or right-aligned title.
titleAngle number

The rotation angle of the header title.

Default value: 0.

titleBaseline TextBaseline

Vertical text baseline for the header title. One of "top", "bottom", "middle".

Default value: "middle"

titleColor Color Color of the header title, can be in hex color code or regular color name.
titleFont string Font of the header title. (e.g., "Helvetica Neue").
titleFontSize number Font size of the header title.
titleFontStyle FontStyle The font style of the header title.
titleFontWeight FontWeight Font weight of the header 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

The maximum length of the header title in pixels. The text value will be automatically truncated if the rendered size exceeds the limit.

Default value: 0, indicating no limit

titleLineHeight number Line height in pixels for multi-line title text.
titleOrient Orient The orientation of the header title. One of "top", "bottom", "left" or "right".
titlePadding number

The padding, in pixel, between facet header’s title and the label.

Default value: 10

Legend Configuration

The Chart.configure_legend() allows you to customize the appearance of chart legends, including location, fonts, bounding boxes, colors, and more. Here is an example:

import altair as alt
from vega_datasets import data

source = data.cars.url

chart = alt.Chart(source).mark_point().encode(
    x='Horsepower:Q',
    y='Miles_per_Gallon:Q',
    color='Origin:N'
)

chart.configure_legend(
    strokeColor='gray',
    fillColor='#EEEEEE',
    padding=10,
    cornerRadius=10,
    orient='top-right'
)

Additional properties are summarized in the following table:

Property Type Description
clipHeight number The height in pixels to clip symbol legend entries and limit their size.
columnPadding number

The horizontal padding in pixels between symbol legend entries.

Default value: 10.

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.
cornerRadius number Corner radius for the full legend.
fillColor anyOf(null, Color) Background fill color for the full legend.
gradientDirection Orientation

The default direction ("horizontal" or "vertical") for gradient legends.

Default value: "vertical".

gradientHorizontalMaxLength number

Max legend length for a horizontal gradient when config.legend.gradientLength is undefined.

Default value: 200

gradientHorizontalMinLength number

Min legend length for a horizontal gradient when config.legend.gradientLength is undefined.

Default value: 100

gradientLabelLimit number The maximum allowed length in pixels of color ramp gradient labels.
gradientLabelOffset number

Vertical offset in pixels for color ramp gradient labels.

Default value: 2.

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.

Default value: 200.

gradientOpacity number Opacity of the color gradient.
gradientStrokeColor anyOf(null, Color)

The color of the gradient stroke, can be in hex color code or regular color name.

Default value: "lightGray".

gradientStrokeWidth number

The width of the gradient stroke, in pixels.

Default value: 0.

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.

Default value: 16.

gradientVerticalMaxLength number

Max legend length for a vertical gradient when config.legend.gradientLength is undefined.

Default value: 200

gradientVerticalMinLength number

Min legend length for a vertical gradient when config.legend.gradientLength is undefined.

Default value: 100

gridAlign LayoutAlign

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.

Default value: "each".

labelAlign Align The alignment of the legend label, can be left, center, or right.
labelBaseline TextBaseline

The position of the baseline of legend label, can be "top", "middle", "bottom", or "alphabetic".

Default value: "middle".

labelColor anyOf(null, Color) 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.

labelFontStyle FontStyle The font style of legend label.
labelFontWeight FontWeight The font weight of legend label.
labelLimit number

Maximum allowed pixel width of legend tick labels.

Default value: 160.

labelOffset number The offset of the legend label.
labelOpacity number Opacity of labels.
labelOverlap LabelOverlap

The strategy to use for resolving overlap of labels in gradient legends. If false, no overlap reduction is attempted. If set to true 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 (this often works better for log-scaled axes).

Default value: "greedy" for log scales otherwisetrue`.

labelPadding number Padding in pixels between the legend and legend labels.
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.
layout LegendLayout Legend orient group layout parameters.
legendX number Custom x-position for legend with orient “none”.
legendY number Custom y-position for legend with orient “none”.
offset number

The offset in pixels by which to displace the legend from the data rectangle and axes.

Default value: 18.

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 between the border and content of the legend group.

Default value: 0.

rowPadding number

The vertical padding in pixels between symbol legend entries.

Default value: 2.

strokeColor anyOf(null, Color) 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.
symbolBaseFillColor anyOf(null, Color)

Default fill color for legend symbols. Only applied if there is no "fill" scale color encoding for the legend.

Default value: "transparent".

symbolBaseStrokeColor anyOf(null, Color)

Default stroke color for legend symbols. Only applied if there is no "fill" scale color encoding for the legend.

Default value: "gray".

symbolDash array(number) An array of alternating [stroke, space] lengths for dashed symbol strokes.
symbolDashOffset number The pixel offset at which to start drawing with the symbol stroke dash array.
symbolDirection Orientation

The default direction ("horizontal" or "vertical") for symbol legends.

Default value: "vertical".

symbolFillColor anyOf(null, Color) The color of the legend symbol,
symbolLimit number The maximum number of allowed entries for a symbol legend. Additional entries will be dropped.
symbolOffset number

Horizontal pixel offset for legend symbols.

Default value: 0.

symbolOpacity number Opacity of the legend symbols.
symbolSize number

The size of the legend symbol, in pixels.

Default value: 100.

symbolStrokeColor anyOf(null, Color) Stroke color for legend symbols.
symbolStrokeWidth number

The width of the symbol’s stroke.

Default value: 1.5.

symbolType SymbolShape

The symbol shape. One of the plotting shapes circle (default), square, cross, diamond, triangle-up, triangle-down, triangle-right, or triangle-left, the line symbol stroke, or one of the centered directional shapes arrow, wedge, or triangle. Alternatively, a custom SVG path string can be provided. For correct sizing, custom shape paths should be defined within a square bounding box with coordinates ranging from -1 to 1 along both the x and y dimensions.

Default value: "circle".

tickCount anyOf(number, TimeInterval) The desired number of tick values for quantitative legends.
title null Set to null to disable title for the axis, legend, or header.
titleAlign Align

Horizontal text alignment for legend titles.

Default value: "left".

titleAnchor TitleAnchor Text anchor position for placing legend titles.
titleBaseline TextBaseline

Vertical text baseline for legend titles.

Default value: "top".

titleColor anyOf(null, Color) 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.
titleFontStyle FontStyle The font style 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 legend titles.

Default value: 180.

titleLineHeight number Line height in pixels for multi-line title text.
titleOpacity number Opacity of the legend title.
titleOrient Orient Orientation of the legend title.
titlePadding number

The padding, in pixels, between title and legend.

Default value: 5.

unselectedOpacity number

The opacity of unselected legend entries.

Default value: 0.35.

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:

For configurations specific to particular mark types, use:

Each of the above methods accepts the following properties:

Property Type Description
align Align The horizontal alignment of the text or ranged marks (area, bar, image, rect, rule). One of "left", "right", "center".
angle number The rotation angle of the text, in degrees.
aspect boolean Whether to keep aspect ratio of image marks.
baseline TextBaseline

The vertical alignment of the text or ranged marks (area, bar, image, rect, rule). One of "top", "middle", "bottom".

Default value: "middle"

color anyOf(Color, Gradient)

Default color.

Default value:

"#4682b4"

Note:

  • This property cannot be used in a style config.
  • The fill and stroke properties have higher precedence than color and will override color.
cornerRadius number

The radius in pixels of rounded rectangle corners.

Default value: 0

cornerRadiusBottomLeft number

The radius in pixels of rounded rectangle bottom left corner.

Default value: 0

cornerRadiusBottomRight number

The radius in pixels of rounded rectangle bottom right corner.

Default value: 0

cornerRadiusTopLeft number

The radius in pixels of rounded rectangle top right corner.

Default value: 0

cornerRadiusTopRight number

The radius in pixels of rounded rectangle top left corner.

Default value: 0

cursor Cursor The mouse cursor used over the mark. Any valid CSS cursor type can be used.
dir Dir

The direction of the text. One of "ltr" (left-to-right) or "rtl" (right-to-left). This property determines on which side is truncated in response to the limit parameter.

Default value: "ltr"

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.
ellipsis string

The ellipsis string for text truncated in response to the limit parameter.

Default value: "…"

fill anyOf(Color, Gradient, null)

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: false for all point, line, and rule marks as well as geoshape marks for graticule data sources; otherwise, true.

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).
height number Height of the marks.
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.
invalid [‘filter’, None]

Defines how Vega-Lite should handle marks for invalid values (null and NaN).

  • If set to "filter" (default), all data items with null values will be skipped (for line, trail, and area marks) or filtered (for other marks).
  • If null, all data items are included. In this case, invalid values will be interpreted as zeroes.
limit number

The maximum length of the text mark in pixels. The text value will be automatically truncated if the rendered size exceeds the limit.

Default value: 0, indicating no limit

lineBreak string A delimiter, such as a newline character, upon which to break text strings into multiple lines. This property will be ignored if the text property is array-valued.
lineHeight number The height, in pixels, of each line of text in a multi-line text mark.
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.

order [null, boolean] For line and trail marks, this order property can be set to null or false to make the lines use the original order in the data sources.
orient Orientation

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 and trail marks, 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

Shape of the point marks. Supported values include:

  • plotting shapes: "circle", "square", "cross", "diamond", "triangle-up", "triangle-down", "triangle-right", or "triangle-left".
  • the line symbol "stroke"
  • centered directional shapes "arrow", "wedge", or "triangle"
  • a custom SVG path string (For correct sizing, custom shape paths should be defined within a square bounding box with coordinates ranging from -1 to 1 along both the x and y dimensions.)

Default value: "circle"

size number

Default size for marks.

  • For point/circle/square, this represents the pixel area of the marks. For example: in the case of circles, the radius is determined in part by the square root of the size value.
  • For bar, this represents the band size of the bar, in pixels.
  • For text, this represents the font size, in pixels.

Default value:

  • 30 for point, circle, square marks; width/height’s step
  • 2 for bar marks with discrete dimensions;
  • 5 for bar marks with continuous dimensions;
  • 11 for text marks.
stroke anyOf(Color, Gradient, null)

Default Stroke Color. This has higher precedence than config.color.

Default value: (None)

strokeCap StrokeCap

The stroke cap for line ending style. One of "butt", "round", or "square".

Default value: "square"

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.
strokeJoin StrokeJoin

The stroke line join method. One of "miter", "round" or "bevel".

Default value: "miter"

strokeMiterLimit number The miter limit at which to bevel a line join.
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 Text 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”.
timeUnitBand number Default relative band size for a time unit. If set to 1, the bandwidth of the marks will be equal to the time unit band step. If set to 0.5, bandwidth of the marks will be half of the time unit band step.
timeUnitBandPosition number Default relative band position for a time unit. If set to 0, the marks will be positioned at the beginning of the time unit band step. If set to 0.5, the marks will be positioned in the middle of the time unit band step.
tooltip anyOf(Value, TooltipContent, null)

The tooltip text string to show upon mouse hover or an object defining which fields should the tooltip be derived from.

  • If tooltip is true or {"content": "encoding"}, then all fields from encoding will be used.
  • If tooltip is {"content": "data"}, then all fields that appear in the highlighted data point will be used.
  • If set to null or false, then no tooltip will be used.

See the tooltip documentation for a detailed discussion about tooltip in Vega-Lite.

Default value: null

width number Width of the marks.
x anyOf(number, [‘width’])

X coordinates of the marks, or width of horizontal "bar" and "area" without specified x2 or width.

The value of this channel can be a number or a string "width" for the width of the plot.

x2 anyOf(number, [‘width’])

X2 coordinates for ranged "area", "bar", "rect", and "rule".

The value of this channel can be a number or a string "width" for the width of the plot.

y anyOf(number, [‘height’])

Y coordinates of the marks, or height of vertical "bar" and "area" without specified y2 or height.

The value of this channel can be a number or a string "height" for the height of the plot.

y2 anyOf(number, [‘height’])

Y2 coordinates for ranged "area", "bar", "rect", and "rule".

The value of this channel can be a number or a string "height" for the height of the plot.

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:

  • barBandPaddingInner for bar marks (0.1 by default)
  • rectBandPaddingInner for rect and other marks (0 by default)
bandPaddingOuter number

Default outer padding for x and y band-ordinal scales.

Default value: paddingInner/2 (which makes width/height = number of unique values * step)

barBandPaddingInner number

Default inner padding for x and y band-ordinal scales of "bar" marks.

Default value: 0.1

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 axis’s size (width or height) - 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 the scale of strokeWidth for rule and line marks and of size for trail marks.

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 the scale of strokeWidth for rule and line marks and of size for trail marks with zero=false.

Default value: 1

pointPadding number

Default outer padding for x and y point-ordinal scales.

Default value: 0.5 (which makes width/height = number of unique values * step)

quantileCount number

Default range cardinality for quantile scale.

Default value: 4

quantizeCount number

Default range cardinality for quantize scale.

Default value: 4

rectBandPaddingInner number

Default inner padding for x and y band-ordinal scales of "rect" marks.

Default value: 0

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.)
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(RangeScheme, array(string)) Default color scheme for categorical data.
diverging anyOf(RangeScheme, array(string)) Default color scheme for diverging quantitative ramps.
heatmap anyOf(RangeScheme, array(string)) Default color scheme for quantitative heatmaps.
ordinal anyOf(RangeScheme, array(string)) Default color scheme for rank-ordered data.
ramp anyOf(RangeScheme, array(string)) Default color scheme for sequential quantitative ramps.
symbol array(SymbolShape) Array of symbol names or paths for the default shape palette.

Projection Configuration

Chart.configure_projection()

Property Type Description
center Vector2<number>

The projection’s center to the specified center, a two-element array of longitude and latitude in degrees.

Default value: [0, 0]

clipAngle number The projection’s clipping circle radius to the specified angle in degrees. If null, switches to antimeridian cutting rather than small-circle clipping.
clipExtent Vector2<Vector2<number>> 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  
parallels array(number)  
precision number 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  
reflectX boolean  
reflectY boolean  
rotate anyOf(Vector2<number>, Vector3<number>)

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]

scale number The projection’s scale (zoom) value, overriding automatic fitting.
spacing number  
tilt number  
translate Vector2<number> The projection’s translation (pan) value, overriding automatic fitting.
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. 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. 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. 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.

Title Configuration

The Chart.configure_title() method allows configuration of the chart title, including the font, color, placement, and orientation. Here is an example:

import altair as alt
from vega_datasets import data

source = data.cars.url

chart = alt.Chart(source).mark_point().encode(
    x='Horsepower:Q',
    y='Miles_per_Gallon:Q',
).properties(
    title='Cars Data'
)

chart.configure_title(
    fontSize=20,
    font='Courier',
    anchor='start',
    color='gray'
)

Additional title configuration options are listed in the following table:

Property Type Description
align Align Horizontal text alignment for title text. One of "left", "center", or "right".
anchor TitleAnchor The anchor position for placing the title and subtitle text. One of "start", "middle", or "end". For example, with an orientation of top these anchor positions map to a left-, center-, or right-aligned title.
angle number Angle in degrees of title and subtitle text.
baseline TextBaseline Vertical text baseline for title and subtitle text. One of "top", "middle", "bottom", or "alphabetic".
color anyOf(null, Color) Text color for title text.
dx number Delta offset for title and subtitle text x-coordinate.
dy number Delta offset for title and subtitle text y-coordinate.
font string Font name for title text.
fontSize number Font size in pixels for title text.
fontStyle FontStyle Font style for title text.
fontWeight FontWeight Font weight for title text. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, …, 900 where "normal" = 400 and "bold" = 700).
frame anyOf(TitleFrame, 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.
offset number The orthogonal offset in pixels by which to displace the title group from its position along the edge of the chart.
orient TitleOrient Default title orientation ("top", "bottom", "left", or "right")
subtitleColor anyOf(null, Color) Text color for subtitle text.
subtitleFont string Font name for subtitle text.
subtitleFontSize number Font size in pixels for subtitle text.
subtitleFontStyle FontStyle Font style for subtitle text.
subtitleFontWeight FontWeight Font weight for subtitle text. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, …, 900 where "normal" = 400 and "bold" = 700).
subtitleLineHeight number Line height in pixels for multi-line subtitle text.
subtitlePadding number The padding in pixels between title and subtitle text.

View Configuration

The Chart.configure_view() method allows you to configure aspects of the chart’s view, i.e. the area of the screen in which the data and scales are drawn. Here is an example to demonstrate some of the visual features that can be controlled:

import altair as alt
from vega_datasets import data

source = data.cars.url

chart = alt.Chart(source).mark_point().encode(
    x='Horsepower:Q',
    y='Miles_per_Gallon:Q',
)

chart.configure_view(
    continuousHeight=200,
    continuousWidth=200,
    strokeWidth=4,
    fill='#FFEEDD',
    stroke='red',
)

Additional properties are summarized in the following table:

Property Type Description
clip boolean Whether the view should be clipped.
continuousHeight number

The default height when the plot has a continuous y-field.

Default value: 200

continuousWidth number

The default width when the plot has a continuous x-field.

Default value: 200

cornerRadius number

The radius in pixels of rounded rectangle corners.

Default value: 0

discreteHeight anyOf(number, dict)

The default height when the plot has either a discrete y-field or no y-field.

Default value: a step size based on config.view.step.

discreteWidth anyOf(number, dict)

The default width when the plot has either a discrete x-field or no x-field.

Default value: a step size based on config.view.step.

fill anyOf(Color, null)

The fill color.

Default value: undefined

fillOpacity number

The fill opacity (value between [0,1]).

Default value: 1

height number Default height
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.

step number Default step size for x-/y- discrete fields.
stroke anyOf(Color, null)

The stroke color.

Default value: "#ddd"

strokeCap StrokeCap

The stroke cap for line ending style. One of "butt", "round", or "square".

Default value: "square"

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.
strokeJoin StrokeJoin

The stroke line join method. One of "miter", "round" or "bevel".

Default value: "miter"

strokeMiterLimit number The miter limit at which to bevel a line join.
strokeOpacity number

The stroke opacity (value between [0,1]).

Default value: 1

strokeWidth number The stroke width, in pixels.
width number Default width

Altair Themes

Altair makes available a theme registry that lets users apply chart configurations globally within any Python session. This is done via the alt.themes object.

The themes registry consists of functions which define a specification dictionary that will be added to every created chart. For example, the default theme configures the default size of a single chart:

>>> import altair as alt
>>> default = alt.themes.get()
>>> default()
{'config': {'view': {'height': 300, 'width': 400}}}

You can see that any chart you create will have this theme applied, and these configurations added to its specification:

import altair as alt
from vega_datasets import data

chart = alt.Chart(data.cars.url).mark_point().encode(
    x='Horsepower:Q',
    y='Miles_per_Gallon:Q'
)

chart.to_dict()
    {'config': {'view': {'continuousWidth': 400, 'continuousHeight': 300}}, 'data': {'url': 'https://vega.github.io/vega-datasets/data/cars.json'}, 'mark': 'point', 'encoding': {'x': {'type': 'quantitative', 'field': 'Horsepower'}, 'y': {'type': 'quantitative', 'field': 'Miles_per_Gallon'}}, '$schema': 'https://vega.github.io/schema/vega-lite/v4.0.0.json'}

The rendered chart will then reflect these configurations:

chart

Changing the Theme

If you would like to enable any other theme for the length of your Python session, you can call alt.themes.enable(theme_name). For example, Altair includes a theme in which the chart background is opaque rather than transparent:

alt.themes.enable('opaque')
chart.to_dict()
    {'config': {'background': 'white', 'view': {'continuousWidth': 400, 'continuousHeight': 300}}, 'data': {'url': 'https://vega.github.io/vega-datasets/data/cars.json'}, 'mark': 'point', 'encoding': {'x': {'type': 'quantitative', 'field': 'Horsepower'}, 'y': {'type': 'quantitative', 'field': 'Miles_per_Gallon'}}, '$schema': 'https://vega.github.io/schema/vega-lite/v4.0.0.json'}
chart

Notice that the background color of the chart is now set to white. If you would like no theme applied to your chart, you can use the theme named 'none':

alt.themes.enable('none')
chart.to_dict()
    {'data': {'url': 'https://vega.github.io/vega-datasets/data/cars.json'}, 'mark': 'point', 'encoding': {'x': {'type': 'quantitative', 'field': 'Horsepower'}, 'y': {'type': 'quantitative', 'field': 'Miles_per_Gallon'}}, '$schema': 'https://vega.github.io/schema/vega-lite/v4.0.0.json'}
chart

Because the view configuration is not set, the chart is smaller than the default rendering.

If you would like to use any theme just for a single chart, you can use the with statement to enable a temporary theme:

with alt.themes.enable('default'):
    spec = chart.to_json()

Currently Altair does not offer many built-in themes, but we plan to add more options in the future.

Defining a Custom Theme

The theme registry also allows defining and registering custom themes. A theme is simply a function that returns a dictionary of default values to be added to the chart specification at rendering time, which is then registered and activated.

For example, here we define a theme in which all marks are drawn with black fill unless otherwise specified:

import altair as alt
from vega_datasets import data

# define the theme by returning the dictionary of configurations
def black_marks():
    return {
        'config': {
            'view': {
                'height': 300,
                'width': 400,
            },
            'mark': {
                'color': 'black',
                'fill': 'black'
            }
        }
    }

# register the custom theme under a chosen name
alt.themes.register('black_marks', black_marks)

# enable the newly registered theme
alt.themes.enable('black_marks')

# draw the chart
cars = data.cars.url
alt.Chart(cars).mark_point().encode(
    x='Horsepower:Q',
    y='Miles_per_Gallon:Q'
)

If you want to restore the default theme, use:

alt.themes.enable('default')

For more ideas on themes, see the Vega Themes repository.