Marks visually encode data using geographic primitives. We currently support VEGA's area, line, rect, rule, symbol, and text marks.
The marks are styled using three encode options. The initial style is set with enter. The markers are updated with the update option. A hover event triggers a hover and a mouseout then styles the point again using update. It should be noted that to save processing, the hover event actually just draws the styled version of the marker on a separate canvas and draws that on top of the existing canvas. This means we can keep a copy of the existing canvas and not have to re-draw everything. The result is that you may be able to see parts of the non-hovered version of the marker depending on how you style the hovered version. This will be more noticeable for text markers.
| Property | Type | Description |
|---|---|---|
| type | String | The type of mark: area, line, rect, rule, symbol, and text. |
| clip | Boolean | This specifies if the marks should be clipped to the chart area. Note that this is more limited that allowed in VEGA |
| name | String | A unique name (without spaces) to reference this mark. |
| description | String | An optional description of this mark shown in the layer choosing menu. If it is the same as other marks, these will be grouped in the layer menu. |
| from | Object | An object describing the data this mark set should visualize. This will reference the data layer name to take the data from e.g. {"data": "lightcurve"}. |
| interactive | Boolean | A boolean flag (default true) indicating if the marks can serve as input event sources. If false, no mouse or touch events corresponding to the marks will be generated. |
| encode | Encode | An object containing a set of visual encoding rules for mark properties. This can contain properties and values that are set using the enter, update, and hover events. |
Area marks are filled areas. See which VEGA properties are supported below
area mark properties| Property | Type | Description |
|---|---|---|
| x | Number | The primary x-coordinate in pixels. |
| x2 | Number | The secondary x-coordinate in pixels. |
| xc | Number | The center x-coordinate. Incompatible with x and x2. |
| width | Number | The width of the mark in pixels, if supported. |
| y | Number | The primary y-coordinate in pixels. |
| y2 | Number | The secondary y-coordinate in pixels. |
| yc | Number | The center y-coordinate. Incompatible with y and y2. |
| height | Number | The height of the mark in pixels, if supported. |
| opacity | Number | The mark opacity from 0 (transparent) to 1 (opaque). |
| fill | Color | The fill color. |
| fillOpacity | Number | The fill opacity from 0 (transparent) to 1 (opaque). |
| stroke | Color | The stroke color. |
| strokeOpacity | Number | The stroke opacity from 0 (transparent) to 1 (opaque). |
| strokeWidth | Number | The stroke width in pixels. |
| strokeCap | String | The stroke cap for line ending style. One of butt (default), round or square. |
| strokeDash | Number[ ] | An array of [stroke, space] lengths for creating dashed or dotted lines. |
| strokeDashOffset | Number | The pixel offset at which to start the stroke dash array. |
| strokeJoin | String | The stroke line join method. One of miter (default), round or bevel. |
| strokeMiterLimit | Number | The miter limit at which to bevel a line join. |
| cursor | String | The mouse cursor used over the mark. Any valid CSS cursor type can be used. |
| href | URL | A URL to load upon mouse click. If defined, the mark acts as a hyperlink. |
| tooltip | Any | The tooltip text to show upon mouse hover. If the value is an object (other than a Date or an array), then all key-value pairs in the object will be shown in the tooltip, one per line (e.g., "key1: value1\nkey2: value2"). Array values will be shown in brackets [value1, value2, ...]. Other values will be coerced to strings. Nested object values will not be recursively printed. |
| zindex | Number | An integer z-index indicating the layering order of sibling mark items. The default value is 0. Higher values (1) will cause marks to be drawn on top of those with lower z-index values. Setting the z-index as an encoding property only affects ordering among sibling mark items; it will not change the layering relative to other mark definitions. Unlike the mark-level sort property, zindex changes the rendering order only; it does not otherwise change mark item order (such as line or area point order). The most common use of zindex is to ensure that a mark is drawn over its siblings when selected, such as by mouse hover. |
Line marks are stroked paths with constant width, defined by an ordered set of (x, y) coordinates. See which VEGA properties are supported below
The VEGA implementation allows a defined flag to say if a data point is defined. If false, the corresponding line segment will be omitted creating a "break". Our implementation allows breaks to be included by inserting undefined values in the data. The following example includes a line with a break and hover events.
line mark properties| Property | Type | Description |
|---|---|---|
| x | Number | The primary x-coordinate in pixels. |
| x2 | Number | The secondary x-coordinate in pixels. |
| xc | Number | The center x-coordinate. Incompatible with x and x2. |
| width | Number | The width of the mark in pixels, if supported. |
| y | Number | The primary y-coordinate in pixels. |
| y2 | Number | The secondary y-coordinate in pixels. |
| yc | Number | The center y-coordinate. Incompatible with y and y2. |
| height | Number | The height of the mark in pixels, if supported. |
| opacity | Number | The mark opacity from 0 (transparent) to 1 (opaque). |
| fill | Color | The fill color. |
| fillOpacity | Number | The fill opacity from 0 (transparent) to 1 (opaque). |
| stroke | Color | The stroke color. |
| strokeOpacity | Number | The stroke opacity from 0 (transparent) to 1 (opaque). |
| strokeWidth | Number | The stroke width in pixels. |
| strokeCap | String | The stroke cap for line ending style. One of butt (default), round or square. |
| strokeDash | Number[ ] | An array of [stroke, space] lengths for creating dashed or dotted lines. |
| strokeDashOffset | Number | The pixel offset at which to start the stroke dash array. |
| strokeJoin | String | The stroke line join method. One of miter (default), round or bevel. |
| strokeMiterLimit | Number | The miter limit at which to bevel a line join. |
| cursor | String | The mouse cursor used over the mark. Any valid CSS cursor type can be used. |
| href | URL | A URL to load upon mouse click. If defined, the mark acts as a hyperlink. |
| tooltip | Any | The tooltip text to show upon mouse hover. If the value is an object (other than a Date or an array), then all key-value pairs in the object will be shown in the tooltip, one per line (e.g., "key1: value1\nkey2: value2"). Array values will be shown in brackets [value1, value2, ...]. Other values will be coerced to strings. Nested object values will not be recursively printed. |
| zindex | Number | An integer z-index indicating the layering order of sibling mark items. The default value is 0. Higher values (1) will cause marks to be drawn on top of those with lower z-index values. Setting the z-index as an encoding property only affects ordering among sibling mark items; it will not change the layering relative to other mark definitions. Unlike the mark-level sort property, zindex changes the rendering order only; it does not otherwise change mark item order (such as line or area point order). The most common use of zindex is to ensure that a mark is drawn over its siblings when selected, such as by mouse hover. |
Rect marks are rectangles with a given position, width and height. They are useful for drawing error bars behind data points. See which VEGA properties are supported below.
rect mark properties| Property | Type | Description |
|---|---|---|
| x | Number | The primary x-coordinate in pixels. |
| x2 | Number | The secondary x-coordinate in pixels. |
| xc | Number | The center x-coordinate. Incompatible with x and x2. |
| width | Number | The width of the mark in pixels, if supported. |
| y | Number | The primary y-coordinate in pixels. |
| y2 | Number | The secondary y-coordinate in pixels. |
| yc | Number | The center y-coordinate. Incompatible with y and y2. |
| height | Number | The height of the mark in pixels, if supported. |
| opacity | Number | The mark opacity from 0 (transparent) to 1 (opaque). |
| fill | Color | The fill color. |
| fillOpacity | Number | The fill opacity from 0 (transparent) to 1 (opaque). |
| stroke | Color | The stroke color. |
| strokeOpacity | Number | The stroke opacity from 0 (transparent) to 1 (opaque). |
| strokeWidth | Number | The stroke width in pixels. |
| strokeCap | String | The stroke cap for line ending style. One of butt (default), round or square. |
| strokeDash | Number[ ] | An array of [stroke, space] lengths for creating dashed or dotted lines. |
| strokeDashOffset | Number | The pixel offset at which to start the stroke dash array. |
| strokeJoin | String | The stroke line join method. One of miter (default), round or bevel. |
| strokeMiterLimit | Number | The miter limit at which to bevel a line join. |
| cursor | String | The mouse cursor used over the mark. Any valid CSS cursor type can be used. |
| href | URL | A URL to load upon mouse click. If defined, the mark acts as a hyperlink. |
| tooltip | Any | The tooltip text to show upon mouse hover. If the value is an object (other than a Date or an array), then all key-value pairs in the object will be shown in the tooltip, one per line (e.g., "key1: value1\nkey2: value2"). Array values will be shown in brackets [value1, value2, ...]. Other values will be coerced to strings. Nested object values will not be recursively printed. |
| zindex | Number | An integer z-index indicating the layering order of sibling mark items. The default value is 0. Higher values (1) will cause marks to be drawn on top of those with lower z-index values. Setting the z-index as an encoding property only affects ordering among sibling mark items; it will not change the layering relative to other mark definitions. Unlike the mark-level sort property, zindex changes the rendering order only; it does not otherwise change mark item order (such as line or area point order). The most common use of zindex is to ensure that a mark is drawn over its siblings when selected, such as by mouse hover. |
Rule marks are simply a line from (x, y) to (x2, y2). These are useful for adding horizontal or vertical lines. See which VEGA properties are supported below.
rule mark properties| Property | Type | Description |
|---|---|---|
| x | Number | The primary x-coordinate in pixels. |
| x2 | Number | The secondary x-coordinate in pixels. |
| xc | Number | The center x-coordinate. Incompatible with x and x2. |
| width | Number | The width of the mark in pixels, if supported. |
| y | Number | The primary y-coordinate in pixels. |
| y2 | Number | The secondary y-coordinate in pixels. |
| yc | Number | The center y-coordinate. Incompatible with y and y2. |
| height | Number | The height of the mark in pixels, if supported. |
| opacity | Number | The mark opacity from 0 (transparent) to 1 (opaque). |
| fill | Color | The fill color. |
| fillOpacity | Number | The fill opacity from 0 (transparent) to 1 (opaque). |
| stroke | Color | The stroke color. |
| strokeOpacity | Number | The stroke opacity from 0 (transparent) to 1 (opaque). |
| strokeWidth | Number | The stroke width in pixels. |
| strokeCap | String | The stroke cap for line ending style. One of butt (default), round or square. |
| strokeDash | Number[ ] | An array of [stroke, space] lengths for creating dashed or dotted lines. |
| strokeDashOffset | Number | The pixel offset at which to start the stroke dash array. |
| strokeJoin | String | The stroke line join method. One of miter (default), round or bevel. |
| strokeMiterLimit | Number | The miter limit at which to bevel a line join. |
| cursor | String | The mouse cursor used over the mark. Any valid CSS cursor type can be used. |
| href | URL | A URL to load upon mouse click. If defined, the mark acts as a hyperlink. |
| tooltip | Any | The tooltip text to show upon mouse hover. If the value is an object (other than a Date or an array), then all key-value pairs in the object will be shown in the tooltip, one per line (e.g., "key1: value1\nkey2: value2"). Array values will be shown in brackets [value1, value2, ...]. Other values will be coerced to strings. Nested object values will not be recursively printed. |
| zindex | Number | An integer z-index indicating the layering order of sibling mark items. The default value is 0. Higher values (1) will cause marks to be drawn on top of those with lower z-index values. Setting the z-index as an encoding property only affects ordering among sibling mark items; it will not change the layering relative to other mark definitions. Unlike the mark-level sort property, zindex changes the rendering order only; it does not otherwise change mark item order (such as line or area point order). The most common use of zindex is to ensure that a mark is drawn over its siblings when selected, such as by mouse hover. |
Symbol marks are useful for plotting data, and include circles, squares and oriented triangles. See which VEGA properties are supported below.
symbol mark properties| Property | Type | Description |
|---|---|---|
| size | Number | The area in pixels of the symbols bounding box. Note that this value sets the area of the symbol; the side lengths will increase with the square root of this value. |
| shape | String | The symbol shape. One of circle (default), square, cross, diamond, triangle-up, triangle-down, triangle-right, triangle-left. A custom SVG path string is not supported. |
| x | Number | The primary x-coordinate in pixels. |
| x2 | Number | The secondary x-coordinate in pixels. |
| xc | Number | The center x-coordinate. Incompatible with x and x2. |
| width | Number | The width of the mark in pixels, if supported. |
| y | Number | The primary y-coordinate in pixels. |
| y2 | Number | The secondary y-coordinate in pixels. |
| yc | Number | The center y-coordinate. Incompatible with y and y2. |
| height | Number | The height of the mark in pixels, if supported. |
| opacity | Number | The mark opacity from 0 (transparent) to 1 (opaque). |
| fill | Color | The fill color. |
| fillOpacity | Number | The fill opacity from 0 (transparent) to 1 (opaque). |
| stroke | Color | The stroke color. |
| strokeOpacity | Number | The stroke opacity from 0 (transparent) to 1 (opaque). |
| strokeWidth | Number | The stroke width in pixels. |
| strokeCap | String | The stroke cap for line ending style. One of butt (default), round or square. |
| strokeDash | Number[ ] | An array of [stroke, space] lengths for creating dashed or dotted lines. |
| strokeDashOffset | Number | The pixel offset at which to start the stroke dash array. |
| strokeJoin | String | The stroke line join method. One of miter (default), round or bevel. |
| strokeMiterLimit | Number | The miter limit at which to bevel a line join. |
| cursor | String | The mouse cursor used over the mark. Any valid CSS cursor type can be used. |
| href | URL | A URL to load upon mouse click. If defined, the mark acts as a hyperlink. |
| tooltip | Any | The tooltip text to show upon mouse hover. If the value is an object (other than a Date or an array), then all key-value pairs in the object will be shown in the tooltip, one per line (e.g., "key1: value1\nkey2: value2"). Array values will be shown in brackets [value1, value2, ...]. Other values will be coerced to strings. Nested object values will not be recursively printed. |
| zindex | Number | An integer z-index indicating the layering order of sibling mark items. The default value is 0. Higher values (1) will cause marks to be drawn on top of those with lower z-index values. Setting the z-index as an encoding property only affects ordering among sibling mark items; it will not change the layering relative to other mark definitions. Unlike the mark-level sort property, zindex changes the rendering order only; it does not otherwise change mark item order (such as line or area point order). The most common use of zindex is to ensure that a mark is drawn over its siblings when selected, such as by mouse hover. |
Text marks are useful for adding labels to a plot. See which VEGA properties are supported below.
text mark properties| Property | Type | Description |
|---|---|---|
| align | String | The horizontal text alignment. One of left (default), center, or right. |
| angle | Number | The rotation angle of the text in degrees (default 0). |
| baseline | String | The vertical text baseline. One of alphabetic (default), top, middle, bottom. |
| dir | String | The direction of the text. One of ltr (left-to-right, default) or rtl (right-to-left). This property determines on which side is truncated in response to the limit parameter. |
| dx | Number | The horizontal offset in pixels (before rotation), between the text and anchor point. |
| dy | Number | The vertical offset in pixels (before rotation), between the text and anchor point. |
| ellipsis | String | The ellipsis string for text truncated in response to the limit parameter (default “…”). |
| font | String | The typeface to set the text in (e.g., Helvetica Neue). |
| fontSize | Number | The font size in pixels. |
| fontWeight | String | Number | The font weight (e.g., normal or bold). |
| fontStyle | String | The font style (e.g., normal or italic). |
| limit | Number | The maximum length of the text mark in pixels (default 0, indicating no limit). The text value will be automatically truncated if the rendered size exceeds the limit. |
| radius | Number | Polar coordinate radial offset in pixels, relative to the origin determined by the x and y properties (default 0). |
| text | String | The text to display. This text may be truncated if the rendered length of the text exceeds the limit parameter. |
| theta | Number | Polar coordinate angle in radians, relative to the origin determined by the x and y properties (default 0). Values for theta follow the same convention of arc marks: angles are measured in radians, with 0 indicating up or “north”. |
| x | Number | The primary x-coordinate in pixels. |
| x2 | Number | The secondary x-coordinate in pixels. |
| xc | Number | The center x-coordinate. Incompatible with x and x2. |
| width | Number | The width of the mark in pixels, if supported. |
| y | Number | The primary y-coordinate in pixels. |
| y2 | Number | The secondary y-coordinate in pixels. |
| yc | Number | The center y-coordinate. Incompatible with y and y2. |
| height | Number | The height of the mark in pixels, if supported. |
| opacity | Number | The mark opacity from 0 (transparent) to 1 (opaque). |
| fill | Color | The fill color. |
| fillOpacity | Number | The fill opacity from 0 (transparent) to 1 (opaque). |
| stroke | Color | The stroke color. |
| strokeOpacity | Number | The stroke opacity from 0 (transparent) to 1 (opaque). |
| strokeWidth | Number | The stroke width in pixels. |
| strokeCap | String | The stroke cap for line ending style. One of butt (default), round or square. |
| strokeDash | Number[ ] | An array of [stroke, space] lengths for creating dashed or dotted lines. |
| strokeDashOffset | Number | The pixel offset at which to start the stroke dash array. |
| strokeJoin | String | The stroke line join method. One of miter (default), round or bevel. |
| strokeMiterLimit | Number | The miter limit at which to bevel a line join. |
| cursor | String | The mouse cursor used over the mark. Any valid CSS cursor type can be used. |
| href | URL | A URL to load upon mouse click. If defined, the mark acts as a hyperlink. |
| tooltip | Any | The tooltip text to show upon mouse hover. If the value is an object (other than a Date or an array), then all key-value pairs in the object will be shown in the tooltip, one per line (e.g., "key1: value1\nkey2: value2"). Array values will be shown in brackets [value1, value2, ...]. Other values will be coerced to strings. Nested object values will not be recursively printed. |
| zindex | Number | An integer z-index indicating the layering order of sibling mark items. The default value is 0. Higher values (1) will cause marks to be drawn on top of those with lower z-index values. Setting the z-index as an encoding property only affects ordering among sibling mark items; it will not change the layering relative to other mark definitions. Unlike the mark-level sort property, zindex changes the rendering order only; it does not otherwise change mark item order (such as line or area point order). The most common use of zindex is to ensure that a mark is drawn over its siblings when selected, such as by mouse hover. |