This website is for Vega-Lite v4. Go to the main Vega-Lite homepage for the latest release.

Text

Edit this page 
// Single View Specification
{
  "data": ... ,
  "mark": "text",
  "encoding": ... ,
  ...
}

text mark represents each data point with a text instead of a point.

Documentation Overview

Text Mark Properties

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

A text mark definition can contain any standard mark properties and the following special properties:

Property Type Description
angle Number | ExprRef

The rotation angle of the text, in degrees.
align String | ExprRef

The horizontal alignment of the text or ranged marks (area, bar, image, rect, rule). One of "left", "right", "center".

Note: Expression reference is not supported for range marks.
baseline String | ExprRef

For text marks, the vertical text baseline. One of "alphabetic" (default), "top", "middle", "bottom", "line-top", "line-bottom", or an expression reference that provides one of the valid values. The "line-top" and "line-bottom" values operate similarly to "top" and "bottom", but are calculated relative to the lineHeight rather than fontSize alone.

For range marks, the vertical alignment of the marks. One of "top", "middle", "bottom".

Note: Expression reference is not supported for range marks.
dir String | ExprRef

The direction of the text. One of "ltr" (left-to-right) or "rtl" (right-to-left). This property determines on which side is truncated in response to the limit parameter.

Default value: "ltr"
dx Number | ExprRef

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 | ExprRef

The vertical offset, in pixels, between the text label and its anchor point. The offset is applied after rotation by the angle property.
ellipsis String | ExprRef

The ellipsis string for text truncated in response to the limit parameter.

Default value: "…"
font String | ExprRef

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

The font size, in pixels.

Default value: 11
fontStyle String | ExprRef

The font style (e.g., "italic").
fontWeight String | Number | ExprRef

The font weight. This can be either a string (e.g "bold", "normal") or a number (100, 200, 300, …, 900 where "normal" = 400 and "bold" = 700).
limit Number | ExprRef

The maximum length of the text mark in pixels. The text value will be automatically truncated if the rendered size exceeds the limit.

Default value: 0 – indicating no limit
lineHeight Number | ExprRef

The line height in pixels (the spacing between subsequent lines of text) for multi-line text marks.
radius Number | ExprRef

For arc mark, the primary (outer) radius in pixels.

For text marks, polar coordinate radial offset, in pixels, of the text from the origin determined by the x and y properties.
text Text | ExprRef

Placeholder text if the text channel is not specified
theta Number | ExprRef

  • For arc marks, the arc length in radians if theta2 is not specified, otherwise the start arc angle. (A value of 0 indicates up or “north”, increasing values proceed clockwise.)

  • For text marks, polar coordinate angle in radians.

Examples

Text Table Heatmap

Labels

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

Scatterplot with Text

Mapping a field to text channel of text mark sets the mark’s text value. For example, we can make a colored scatterplot with text marks showing the initial character of its origin, instead of point marks.

Geo Text

By mapping geographic coordinate data to longitude and latitude channels of a corresponding projection, we can show text at accurate locations. The example below shows the name of every US state capital at the location of the capital.

Text Config

// Top-level View Specification
{
  ...
  "config": {
    "text": ...,
    ...
  }
}

The text property of the top-level config object sets the default properties for all text marks. If mark property encoding channels are specified for marks, these config values will be overridden.