This website is for Vega-Lite v3. 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

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

The horizontal alignment of the text. One of "left", "right", "center".
baseline String

The vertical alignment of the text. One of "top", "middle", "bottom".

Default value: "middle"
dir String

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

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

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

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

Default value: "…"
font String

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

The font size, in pixels.
fontStyle FontStyle

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

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

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
radius Number

Polar coordinate radial offset, in pixels, of the text label from the origin determined by the x and y properties.
text String

Placeholder text if the text channel is not specified
theta Number

Polar coordinate angle, in radians, of the text label from the origin determined by the x and y properties. Values for theta follow the same convention of arc mark startAngle and endAngle properties: angles are measured in radians, with 0 indicating “north”.

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.

Besides standard mark properties and special properties for text marks, text config can contain the following additional properties:

Property Type Description
shortTimeLabels Boolean

Whether month names and weekday names should be abbreviated.