Shape Mark

Shape marks are arbitrary shapes whose geometry is determined at render time. Whereas path marks require SVG path strings, shape marks instead require a shape instance with a drawing function that is later invoked upon render. Canvas rendering with shape marks can improve performance, as no intermediate representation (such as an SVG path string) needs to be parsed.

The primary use case for shape marks is drawing dynamic maps, using the shape instance provided by the geoshape transform.

Type-Specific Mark Properties

Property Type Description
shape Shape An shape instance that provides a drawing method to invoke within the renderer. Shape instances can not be specified directly, they must be generated by a data transform such as geoshape.

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

For marks that support width and height settings (including rect and area), the horizontal dimensions are determined (in order of precedence) by the x and x2 properties, the x and width properties, the x2 and width properties, or the xc and width properties. If all three of x, x2 and width are specified, the width value is ignored. The y, y2, yc and height properties are treated similarly.

For marks that do not support width or height (including path and arc) similar calculations are applied, but are only used to determine the mark’s ultimate x and y position. The width property may affect the final x position, but otherwise is not visualized.

When using multiple spatial properties along the same dimension (x and x2, or y and y2), the properties must be specified in the same encoding set; for example, all within "enter": {...} or all within "update": {...}. Dividing the properties across encoding sets can cause unexpected behavior.