Mark

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

• Documentation Overview
• Mark Types
• Mark Definition Object
  • General Mark Properties
  • Position and Offset Properties
  • Color Properties
  • Stroke Style Properties
  • Hyperlink Properties
• 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

Position and Offset Properties

Color Properties

Stroke Style Properties

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.

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:

1. If mark properties in mark definition or mark property encoding channels are specified, these config values will be overridden.
2. 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.

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.

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