Text Mark

Text marks can be used to annotate data, and provide labels and titles for axes and legends.

Example

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

The x and y properties determine an anchor point for the text. Additional positioning parameters, including dx, dy, radius, and theta, are applied relative to this point.

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 String The tooltip text to show upon 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.