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 supported mark types are "area", "bar", "circle", "line", "point", "rect", "rule", "square", "text", and "tick". 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.

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

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

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

Documentation Overview

Mark Definition Object

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

A mark definition object can contains the following properties and all properties of the mark config:

Property Type Description
type String

Required. The mark type. One of "bar", "circle", "square", "tick", "line", "area", "point", "rule", and "text".

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

clip Boolean

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

Example: Filled Points

By default, point marks have filled borders and are transparent inside. Setting filled to true creates filled points instead.

Example: Interpolate with monotone

Example: Interpolate with line-step (Step-Chart)

Example: Offsetting Labels

You can use text marks as labels and set its offset (dx or dy), align, and baseline properties of the mark definition.

Mark Config

// Top-level View Specification
{
  ...
  "config": {
    "mark": ...,
    "area": ...,
    "bar": ...,
    "circle": ...,
    "line": ...,
    "point": ...,
    "rect": ...,
    "rule": ...,
    "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.

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

The rest of this section describe groups of properties supported by the mark config and all mark-specific configs. Besides the properties listed below, "bar", "text", and "tick" marks contain additional mark-specific config properties:

Color

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

color String

Default color. Note that fill and stroke have higher precedence than color and will override color.

Default value: "#4682b4"

Note: This property cannot be used in a style config.

fill String

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

Default value: (None)

stroke String

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

Default value: (None)

Opacity

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

fillOpacity Number

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

Default value: 1

strokeOpacity Number

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

Default value: 1

Stroke Style

Property Type Description
strokeWidth Number

The stroke width, in pixels.

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

Interpolation (for Line and Area Marks)

Property Type Description
interpolate String

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

Depending on the interpolation type, sets the tension parameter (for line and area marks).

Orientation (for Bar, Tick, Line, and Area Marks)

Property Type Description
orient String

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.

Shape Config (for Point)

Property Type Description
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"

Point Size Config (for Point, Circle, and Square Marks)

Property Type Description
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

Text Config (for Text Marks)

Property Type Description
angle Number

The rotation angle of the text, in degrees.

align String

The horizontal alignment of the text. One of "left", "right", "center".

baseline String

The vertical alignment of the text. One of "top", "middle", "bottom".

Default value: "middle"

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.

font String

The typeface to set the text in (e.g., "Helvetica Neue").

fontSize Number

The font size, in pixels.

fontStyle String

The font style (e.g., "italic").

fontWeight String | Number

The font weight (e.g., "bold").

radius Number

Polar coordinate radial offset, in pixels, of the text label from the origin determined by the x and y properties.

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

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

In addition to custom style names, Vega-Lite 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

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.

See also: a similar example that uses mark definition to configure offset, align, and baseline.