`mark_text()` creates a text mark: an Altair layer that displays words, labels, or values at encoded positions. Use it when the audience should not have to calculate, decode a distant legend, or infer the takeaway from a chart alone. Text can annotate a finding, identify a series directly, show bar values, provide explanatory context, or present a next step. section 2.3.1 section 3.3.1 section 6.3.2
Start with a shared base chart when text should align with an existing visualization. Put data-dependent properties in `encode()`—for example `text='label:N'` or a conditional text color. Put static styling in `mark_text()`, such as `fontSize`, `align`, `baseline`, `dx`, `color`, `x`, and `y`. This separation lets one layer inherit position channels while adding only the text-specific details. section 2.3.1 section 6.3.3
Annotate the end of each line
A line chart can replace its legend with labels placed beside the final data point. Build a base with month, order count, and meal type encodings; create the line layer; then filter the text layer to December. `dx=10`, `align='left'`, and `baseline='middle'` move each label just beyond its line. `text = base.mark_text(fontSize=14, baseline='middle', align='left', dx=10).encode(text=alt.Text('Meal Type:N')).transform_filter(alt.datum['Month'] == 'December')` Layer it with `chart = base.mark_line() + text`. Direct labels make the series easier to identify without matching colors to a separate legend. section 6.3.3 section 3.3.1
Listing 2.13 Adding an annotation to the chart
annotation = base.mark_text(
dx=10, #1
align='left', #2
fontSize=12 #3
).encode(
text='label:N'
).transform_filter(
alt.datum.Year == 2018
).transform_calculate(
label='datum.Country + "(" + format(datum.PI, ".2f") + "%)"' #4
)
chart = (chart + annotation
)
chart.save('chart.html')
This listing layers a filtered text annotation onto a percentage-increase line chart. It formats a label with `transform_calculate()`, selects 2018 with `transform_filter()`, and offsets left-aligned text with `dx`. section 2.3.1
For a bar chart, reuse the bar chart’s encodings and add a text layer with the value field in the text channel. A left-aligned, vertically centered label with a small positive `dx` sits just beyond each bar. Pairing values with light reference rules can support comparison while allowing the x-axis to be removed for a less cluttered result. section 6.3.2
Text marks also carry narrative context. Create a small DataFrame containing a multiline statement, encode its text field, and set `lineBreak='\n'` with fixed alignment, size, position, and color. Layer or concatenate that commentary with the main chart and supporting charts to explain why a pattern matters or to present calls to action. section 2.3.2 section 9.2.2
