Mark

Edit this page

Marks are the basic visual building block of a visualization. They provide basic shapes whose properties (such as position, size, and color) can be used to visually encode data, either from a data field, or a constant value.

The mark property of a single view specification can either be (1) a string describing a mark type or (2) a mark definition object.

// Single View Specification
{
  "data": ... ,
  "mark": ... ,       // mark
  "encoding": ... ,
  ...
}

Documentation Overview

Mark Types
Mark Definition Object
Mark Config
Mark Style Config
- Example: Styling Labels

Mark Types

Vega-Lite supports the following primitive mark types: "area", "bar", "circle", "line", "point", "rect", "rule", "square", "text", "tick", and "geoshape". In general, one mark instance is generated per input data element. However, line and area marks represent multiple data elements as a contiguous line or shape.

In addition to primitive marks, Vega-Lite also support composite marks, which are “macros” for complex layered graphics that contain multiple primitive marks. Supported composite mark types include "boxplot", "errorband", "errorbar".

For example, a bar chart has mark as a simple string "bar".

Mark Definition Object

// Single View Specification
{
  ...
  "mark": {
    "type": ...,       // mark
    ...
  },
  ...
}

To customize properties of a mark, users can set mark to be a mark definition object instead of a string describing mark type. The rest of this section lists standard mark properties for primitive mark types. Additionally, some marks may have special mark properties (listed in their documentation page). For example, point marks support shape and size properties in addition to these standard properties.

Note: If mark property encoding channels are specified, these mark properties will be overridden.

General Mark Properties

Property	Type	Description
type	String	*Required.* The mark type. This could a primitive mark type (one of `"bar"`, `"circle"`, `"square"`, `"tick"`, `"line"`, `"area"`, `"point"`, `"geoshape"`, `"rule"`, and `"text"`) or a composite mark type (`"boxplot"`, `"errorband"`, `"errorbar"`).
aria	Boolean \| ExprRef	A boolean flag indicating if ARIA attributes 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	String \| ExprRef	A text description of the mark item for ARIA accessibility (SVG output only). If specified, this property determines the “aria-label” attribute.
style	String \| 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. If style is an array, later styles will override earlier styles. Any mark properties 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	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` documentation for a detailed discussion about tooltip in Vega-Lite. Default value: `null`
clip	Boolean \| ExprRef	Whether a mark be clipped to the enclosing group’s width and height.
invalid	String \| 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

Property	Type	Description
x	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	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	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	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	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	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	Number \| ExprRef	Offset for x-position.
x2Offset	Number \| ExprRef	Offset for x2-position.
yOffset	Number \| ExprRef	Offset for y-position.
y2Offset	Number \| ExprRef	Offset for y2-position.

Color Properties

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` data sources; otherwise, `true`. Note: This property cannot be used in a style config.
color	Color \| Gradient \| ExprRef	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`.
fill	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	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	Blend \| ExprRef	The color blend mode for drawing an item on its current background. Any valid CSS mix-blend-mode value can be used. __Default value: `"source-over"`
opacity	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	Number \| ExprRef	The fill opacity (value between [0,1]). Default value: `1`
strokeOpacity	Number \| ExprRef	The stroke opacity (value between [0,1]). Default value: `1`

Stroke Style Properties

Property	Type	Description
strokeCap	String \| ExprRef	The stroke cap for line ending style. One of `"butt"`, `"round"`, or `"square"`. Default value: `"butt"`
strokeDash	Number[] \| ExprRef	An array of alternating stroke, space lengths for creating dashed or dotted lines.
strokeDashOffset	Number \| ExprRef	The offset (in pixels) into which to begin drawing with the stroke dash array.
strokeJoin	String \| ExprRef	The stroke line join method. One of `"miter"`, `"round"` or `"bevel"`. Default value: `"miter"`
strokeMiterLimit	Number \| ExprRef	The miter limit at which to bevel a line join.
strokeWidth	Number \| ExprRef	The stroke width, in pixels.

Here is an example to the usage of the stroke dash where 6 is the size of dashes, and 4 is the size of spaces:

Hyperlink Properties

Marks can act as hyperlinks when the href property or channel is defined. When the href property is specified, the cursor mark property is set to "pointer" by default to serve as affordance for hyperlinks.

Property	Type	Description
href	URI \| ExprRef	A URL to load upon mouse click. If defined, the mark acts as a hyperlink.
cursor	String \| ExprRef	The mouse cursor used over the mark. Any valid CSS cursor type can be used.

Mark Config

// Top-level View Specification
{
  ...
  "config": {
    "mark": ...,
    "area": ...,
    "bar": ...,
    "circle": ...,
    "line": ...,
    "point": ...,
    "rect": ...,
    "rule": ...,
    "geoshape": ...,
    "square": ...,
    "text": ...,
    "tick": ...
  }
}

The mark property of the config object sets the default properties for all marks. In addition, the config object also provides mark-specific config using its mark type as the property name (e.g., config.area) for defining default properties for each mark.

The global mark config (config.mark) supports all standard mark properties (except type, style, clip, and orient). For mark-specific config, please see the documentation for each mark type.

Note:

If mark properties in mark definition or mark property encoding channels are specified, these config values will be overridden.
Mark config do not support offset mark properties.

Mark Style Config

{
  // Top Level Specification
  "config": {
    "style": {
      ...
    }
    ...
  }
}

In addition to the default mark properties above, default values can be further customized using named styles defined under the style property in the config object.

Property	Type	Description
style	Object	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.

For example, to set a default shape and stroke width for point marks with a style named "triangle":

{
  "style": {
    "triangle": {
      "shape": "triangle-up",
      "strokeWidth": 2
    }
  }
}

Styles can then be invoked by including a style property within a mark definition object.

Note: To customize the style for guides (axes, headers, and legends), Vega-Lite also includes the following built-in style names:

"guide-label": style for axis, legend, and header labels
"guide-title": style for axis, legend, and header titles
"group-title": styles for chart titles

Example: Styling Labels

You can use text marks as labels for other marks by setting style for the marks and using style config to configure offset (dx or dy), align, and baseline.