Marks#

We saw in Encodings that the encode() method is used to map columns to visual attributes of the plot. The mark property is what specifies how exactly those attributes should be represented on the plot.

Altair supports the following primitive mark types:

Mark

Method

Description

Arc

mark_arc()

A pie chart.

Area

mark_area()

A filled area plot.

Bar

mark_bar()

A bar plot.

Circle

mark_circle()

A scatter plot with filled circles.

Geoshape

mark_geoshape()

Visualization containing spatial data

Image

mark_image()

A scatter plot with image markers.

Line

mark_line()

A line plot.

Point

mark_point()

A scatter plot with configurable point shapes.

Rect

mark_rect()

A filled rectangle, used for heatmaps

Rule

mark_rule()

A vertical or horizontal line spanning the axis.

Square

mark_square()

A scatter plot with filled squares.

Text

mark_text()

A scatter plot with points represented by text.

Tick

mark_tick()

A vertical or horizontal tick mark.

Trail

mark_trail()

A line with variable widths.

In addition, Altair provides the following composite marks:

Mark Name

Method

Description

Example

Box Plot

mark_boxplot()

A box plot.

Boxplot with Min/Max Whiskers

Error Band

mark_errorband()

A continuous band around a line.

Line Chart with Confidence Interval Band

Error Bar

mark_errorbar()

An error bar around a point.

Error Bars with Confidence Interval

In Altair, marks can be most conveniently specified by the mark_* methods of the Chart object (e.g. mark_bar), which take optional keyword arguments to configure the look of the marks.

Mark Properties#

This section lists standard mark properties for primitive mark types. Additionally, some marks may have special mark properties (listed in their documentation page).

General Mark Properties#

Click to show table

Property

Type

Description

aria

anyOf(boolean, ExprRef)

A boolean flag indicating if ARIA attributes <https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA>__ should be included (SVG output only). If false, the “aria-hidden” attribute will be set on the output SVG element, removing the mark item from the ARIA accessibility tree.

description

anyOf(string, ExprRef)

A text description of the mark item for ARIA accessibility <https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA>__ (SVG output only). If specified, this property determines the "aria-label" attribute <https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute>__.

style

anyOf(string, array(string))

A string or array of strings indicating the name of custom styles to apply to the mark. A style is a named collection of mark property defaults defined within the style configuration <https://vega.github.io/vega-lite/docs/mark.html#style-config>. If style is an array, later styles will override earlier styles. Any mark properties <https://vega.github.io/vega-lite/docs/encoding.html#mark-prop> explicitly defined within the encoding will override a style default.

Default value: The mark’s name. For example, a bar mark will have style "bar" by default. Note: Any specified style will augment the default style. For example, a bar mark with "style": "foo" will receive from config.style.bar and config.style.foo (the specified style "foo" has higher precedence).

tooltip

anyOf(number, string, boolean, TooltipContent, ExprRef, 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 <https://vega.github.io/vega-lite/docs/tooltip.html>__ documentation for a detailed discussion about tooltip in Vega-Lite.

Default value: null

clip

anyOf(boolean, ExprRef)

Whether a mark be clipped to the enclosing group’s width and height.

invalid

anyOf(MarkInvalidDataMode, null)

Invalid data mode, which defines how the marks and corresponding scales should represent invalid values (null and NaN in continuous scales without defined output for invalid values).

  • "filter" — Exclude all invalid values from the visualization’s marks and scales. For path marks (for line, area, trail), this option will create paths that connect valid points, as if the data rows with invalid values do not exist.

  • "break-paths-filter-domains" — Break path marks (for line, area, trail) at invalid values. For non-path marks, this is equivalent to "filter". All scale domains will exclude these filtered data points.

  • "break-paths-show-domains" — Break paths (for line, area, trail) at invalid values. Hide invalid values for non-path marks. All scale domains will include these filtered data points (for both path and non-path marks).

  • "show" or null — Show all data points in the marks and scale domains. Each scale will use the output for invalid values defined in config.scale.invalid or, if unspecified, by default invalid values will produce the same visual values as zero (if the scale includes zero) or the minimum value (if the scale does not include zero).

  • "break-paths-show-path-domains" (default) — This is equivalent to "break-paths-show-domains" for path-based marks (line/area/trail) and "filter" for non-path marks.

Note: If any channel’s scale has an output for invalid values defined in config.scale.invalid, all values for the scales will be considered “valid” since they can produce a reasonable output for the scales. Thus, fields for such channels will not be filtered and will not cause path breaks.

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.

Position and Offset Properties#

Click to show table

Property

Type

Description

x

anyOf(number, string, ExprRef)

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, string, ExprRef)

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.

width

anyOf(number, ExprRef, RelativeBandSize)

Width of the marks. One of:

  • A number representing a fixed pixel width.

  • A relative band size definition. For example, {band: 0.5} represents half of the band.

height

anyOf(number, ExprRef, RelativeBandSize)

Height of the marks. One of:

  • A number representing a fixed pixel height.

  • A relative band size definition. For example, {band: 0.5} represents half of the band

y

anyOf(number, string, ExprRef)

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, string, ExprRef)

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.

xOffset

anyOf(number, ExprRef)

Offset for x-position.

x2Offset

anyOf(number, ExprRef)

Offset for x2-position.

yOffset

anyOf(number, ExprRef)

Offset for y-position.

y2Offset

anyOf(number, ExprRef)

Offset for y2-position.

Color Properties#

Click to show table

Property

Type

Description

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 <https://vega.github.io/vega-lite/docs/data.html#graticule>__ data sources; otherwise, true.

Note: This property cannot be used in a style config <https://vega.github.io/vega-lite/docs/mark.html#style-config>__.

color

anyOf(Color, Gradient, ExprRef)

Default color.

Default value: :raw-html:<span style="color: #4682b4;"> ■ :raw-html:</span> "#4682b4"

Note:

  • This property cannot be used in a style config <https://vega.github.io/vega-lite/docs/mark.html#style-config>__.

  • The fill and stroke properties have higher precedence than color and will override color.

fill

anyOf(Color, Gradient, null, ExprRef)

Default fill color. This property has higher precedence than config.color. Set to null to remove fill.

Default value: (None)

stroke

anyOf(Color, Gradient, null, ExprRef)

Default stroke color. This property has higher precedence than config.color. Set to null to remove stroke.

Default value: (None)

blend

anyOf(Blend, ExprRef)

The color blend mode for drawing an item on its current background. Any valid CSS mix-blend-mode <https://developer.mozilla.org/en-US/docs/Web/CSS/mix-blend-mode>__ value can be used.

Default value: "source-over"

opacity

anyOf(number, ExprRef)

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.

fillOpacity

anyOf(number, ExprRef)

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

Default value: 1

strokeOpacity

anyOf(number, ExprRef)

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

Default value: 1

Stroke Style Properties#

Click to show table

Property

Type

Description

strokeCap

anyOf(StrokeCap, ExprRef)

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

Default value: "butt"

strokeDash

anyOf(array(number), ExprRef)

An array of alternating stroke, space lengths for creating dashed or dotted lines.

strokeDashOffset

anyOf(number, ExprRef)

The offset (in pixels) into which to begin drawing with the stroke dash array.

strokeJoin

anyOf(StrokeJoin, ExprRef)

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

Default value: "miter"

strokeMiterLimit

anyOf(number, ExprRef)

The miter limit at which to bevel a line join.

strokeWidth

anyOf(number, ExprRef)

The stroke width, in pixels.