Ctrl+K
This website is for version 5. You can find the documentation for version 4 here.

Vega-Altair

Text#

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

Text Mark Properties#

Click to show code
import altair as alt
import pandas as pd

angle_slider = alt.binding_range(min=-180, max=180, step=1)
angle_var = alt.param(bind=angle_slider, value=0, name="angle")

dx_slider = alt.binding_range(min=-20, max=20, step=1)
dx_var = alt.param(bind=dx_slider, value=5, name="dx")

dy_slider = alt.binding_range(min=-20, max=20, step=1)
dy_var = alt.param(bind=dy_slider, value=0, name="dy")

xOffset_slider = alt.binding_range(min=-20, max=20, step=1)
xOffset_var = alt.param(bind=xOffset_slider, value=0, name="xOffset")

yOffset_slider = alt.binding_range(min=-20, max=20, step=1)
yOffset_var = alt.param(bind=yOffset_slider, value=0, name="yOffset")

fontSize_slider = alt.binding_range(min=1, max=36, step=1)
fontSize_var = alt.param(bind=fontSize_slider, value=14, name="fontSize")

limit_slider = alt.binding_range(min=0, max=150, step=1)
limit_var = alt.param(bind=limit_slider, value=0, name="limit")

align_select = alt.binding_select(options=["left", "center", "right"])
align_var = alt.param(bind=align_select, value="left", name="align")

baseline_select = alt.binding_select(options=["alphabetic", "top", "middle", "bottom"])
baseline_var = alt.param(bind=baseline_select, value="midle", name="baseline")

font_select = alt.binding_select(options=["sans-serif", "serif", "monospace"])
font_var = alt.param(bind=font_select, value="sans-serif", name="font")

fontWeight_select = alt.binding_select(options=["normal", "bold"])
fontWeight_var = alt.param(bind=fontWeight_select, value="normal", name="fontWeight")

fontStyle_select = alt.binding_select(options=["normal", "italic"])
fontStyle_var = alt.param(bind=fontStyle_select, value="normal", name="fontStyle")

source = pd.DataFrame(
    {
        "a": [30, 25, 70],
        "b": [28, 65, 43],
        "label": ["Andy", "Brian", "Charlie"],
    }
)

base = alt.Chart(source).encode(
    x=alt.X("a:Q").axis(labelAngle=0).scale(domain=[0, 100]),
    y=alt.Y("b:Q").scale(domain=[0, 100]),
)

pts = base.mark_point()

text = base.mark_text(
    dx=dx_var,
    dy=dy_var,
    xOffset=xOffset_var,
    yOffset=yOffset_var,
    angle=angle_var,
    align=align_var,
    baseline=baseline_var,
    font=font_var,
    fontSize=fontSize_var,
    fontStyle=fontStyle_var,
    fontWeight=fontWeight_var,
    limit=limit_var,
).encode(text="label:N")

(pts + text).add_params(
    dx_var,
    dy_var,
    xOffset_var,
    yOffset_var,
    angle_var,
    align_var,
    baseline_var,
    font_var,
    fontSize_var,
    fontStyle_var,
    fontWeight_var,
    limit_var,
)

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

Click to show table

Property

Type

Description

angle

anyOf(number, ExprRef)

The rotation angle of the text, in degrees.

align

anyOf(Align, 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

anyOf(TextBaseline, 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

anyOf(TextDirection, 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

anyOf(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

anyOf(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

anyOf(string, ExprRef)

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

Default value: "…"

font

anyOf(string, ExprRef)

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

fontSize

anyOf(number, ExprRef)

The font size, in pixels.

Default value: 11

fontStyle

anyOf(FontStyle, ExprRef)

The font style (e.g., "italic").

fontWeight

anyOf(FontWeight, 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

anyOf(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

anyOf(number, ExprRef)

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

radius

anyOf(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.

Default value: min(plot_width, plot_height)/2

text

anyOf(Text, ExprRef)

Placeholder text if the text channel is not specified

theta

anyOf(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#

import altair as alt
from vega_datasets import data

source = data.cars()

base = alt.Chart(source).transform_aggregate(
    num_cars="count()",
    groupby=["Origin", "Cylinders"],
).encode(
    alt.X("Cylinders:O").scale(paddingInner=0),
    alt.Y("Origin:O").scale(paddingInner=0),
)

heatmap = base.mark_rect().encode(
    alt.Color("num_cars:Q")
        .scale(scheme="viridis")
        .legend(direction="horizontal")
)

text = base.mark_text(baseline="middle").encode(
    text="num_cars:Q",
    color=alt.condition(
        alt.datum.num_cars > 100,
        alt.value("black"),
        alt.value("white"),
    ),
)

heatmap + text

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.

import altair as alt
import pandas as pd

source = pd.DataFrame({
    "a": ["A", "B", "C"],
    "b": [28, 55, 43]
})

bar = alt.Chart(source).mark_bar().encode(
    y="a:N",
    x=alt.X("b:Q").scale(domain=[0, 60])
)
text = bar.mark_text(
    align="left",
    baseline="middle",
    dx=3
).encode(text="b")

bar + text

Labels Position Based on Condition#

By default, text mark as labels in Altair are positioned above or to the right of the value. However, when dealing with negative values, this default positioning can lead to label overlap with the bar. To address this issue, you can set label positions via Expressions. Here’s an example demonstrating how to do this:

import altair as alt
import pandas as pd

source = pd.DataFrame({
    "a": ["A", "B", "C"],
    "b": [28, -5, 10]
})

bar = alt.Chart(source).mark_bar().encode(
    y="a:N",
    x=alt.X("b:Q").scale(domain=[-10, 35])
)

text_conditioned = bar.mark_text(
    align="left",
    baseline="middle",
    dx=alt.expr(alt.expr.if_(alt.datum.b >= 0, 10, -20))
).encode(text="b")

bar + text_conditioned

Scatter Plot with Text#

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

import altair as alt
from vega_datasets import data
from altair import datum

source = data.cars()

alt.Chart(source).mark_text().encode(
    x="Horsepower:Q",
    y="Miles_per_Gallon:Q",
    color="Origin:N",
    text="Origin[0]:N",
)

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.

import altair as alt
from vega_datasets import data

states = alt.topo_feature(data.us_10m.url, feature="states")

source = data.us_state_capitals()

background = alt.Chart(states).mark_geoshape(
    fill="lightgray",
    stroke="white",
).properties(
    width=750,
    height=500,
).project("albersUsa")

line = alt.Chart(source).mark_text(dy=-10).encode(
    latitude="lat:Q",
    longitude="lon:Q",
    text="city:N"
)

point = alt.Chart(source).mark_circle().encode(
    latitude="lat:Q",
    longitude="lon:Q",
    color=alt.value("orange"),
)

background + line + point
On this page