text
Draws a text label for each data item. Used for value labels on bars, point annotations, node names in diagrams, and axis titles.
gf.chart([{ label: "GoFish" }])
.mark(gf.text({ text: "label", fontSize: 28, fill: "steelblue" }))
.render(root, { w: 240, h: 80 });Signature
text({ text, fill = "black", stroke?, strokeWidth = 0, fontSize = 12,
fontFamily = "system-ui, sans-serif", fontStyle?, fontWeight?, rotate = 0,
textAnchor = "start", debugBoundingBox = false, x?, y?, w?, h? })Parameters
A text label. Box geometry via the shared dims channels positions the text anchor.
| Option | Type | Default | Description |
|---|---|---|---|
filter | Filter | string | A filter over this whole drawing: a Filter strategy (Filter.grayscale(), Filter.luminanceToAlpha()) or a raw CSS filter string ("blur(2px)", "url(#shadow)"). | |
key | string | Internal per-node key override. | |
text | string | FieldExpr | Required. Text content (raw channel — a literal, field name, or accessor). | |
fill | string | FieldExpr | "black" | Fill color, or a field name for a color scale. |
stroke | string | FieldExpr | Stroke color. | |
strokeWidth | number | 0 | Stroke width in pixels. |
fontSize | number | 12 | Font size in pixels. |
fontFamily | string | "system-ui, sans-serif" | Font family. |
fontStyle | string | Raw CSS font-style (e.g. "italic"). | |
fontWeight | number | string | CSS font-weight (e.g. 300, 700, "bold"). | |
debugBoundingBox | boolean | false | Draw the text's bounding box, for layout debugging. |
rotate | number | 0 | Rotation in degrees, clockwise on screen, about the text anchor. |
textAnchor | "start" | "middle" | "end" | "start" | Where the text anchor — the local origin rotate pivots about and x places — sits along the string: its first character, center, or last character. cx places the center of the text's box whatever the anchor. |
Box dimensions
| Option | Type | Default | Description |
|---|---|---|---|
x | number | string | FieldExpr | Left edge position. | |
cx | number | string | FieldExpr | Center x. | |
x2 | number | string | FieldExpr | Right edge position. | |
w | number | string | FieldExpr | Width. | |
emX | boolean | Embed x in the parent's x space. | |
y | number | string | FieldExpr | Start edge on y: the top edge where y reads top-down, the bottom edge where it grows upward. | |
cy | number | string | FieldExpr | Center y. | |
y2 | number | string | FieldExpr | Other y edge position. | |
h | number | string | FieldExpr | Height. | |
emY | boolean | Embed y in the parent's y space. | |
dims | Record<string, AxisDimsValue> | Box dimensions by axis name: x/y, or a name the enclosing coordinate space declares (polar theta/r, geo lon/lat). Each value is a position (like x) or an interval {min, center, max, size, embedded}. |
Placement
A text is a box, and it is placed exactly as a rect of the same size would be. y is the box's start edge: its top where y reads top-down (a free diagram, an ordinal spread) and its bottom where y grows upward (a chart with a value axis). cy is the box's center. Spreads, stacks, layers and align/distribute constraints place it by its box, as they place a rect. In x, x is the textAnchor point: the left edge for the default "start" (as for a rect), the center for "middle", the right edge for "end". cx is the box's center, whatever the anchor.
rotate turns the glyphs about the point on their baseline at textAnchor; the box is then the rotated glyphs' footprint.
Examples
// Static label
.mark(text({ text: "Hello", fontSize: 24, fill: "steelblue" }))
// Text content read from a data field
.mark(text({ text: "name" }))
// Value labels: layer text totals on top of bars
layer([
chart(seafood)
.flow(spread({ by: "lake", dir: "x" }))
.mark(rect({ h: "count" }).name("bars")),
chart(selectAll("bars"))
.flow(group({ by: "lake" }))
.mark((d) =>
// A spread on y reads top-down: the total above its bar.
spread({ dir: "y", alignment: "middle", spacing: 10 }, [
text({ text: String(sumBy(d[0].datum, "count")) }),
d[0],
])
),
]);
// Rotated y-axis title (reads bottom-to-top): rotate is clockwise on screen
.mark(text({ text: "count", rotate: -90, fontSize: 13 }))
// Italic label
.mark(text({ text: "note", fontStyle: "italic" }))
// Light-weight label
.mark(text({ text: "caption", fontWeight: 300 }))