Skip to content

text ​

Draws a text label for each data item. Used for value labels on bars, point annotations, node names in diagrams, and axis titles.

js
gf.chart([{ label: "GoFish" }])
  .mark(gf.text({ text: "label", fontSize: 28, fill: "steelblue" }))
  .render(root, { w: 240, h: 80 });

Signature ​

ts
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.

OptionTypeDefaultDescription
filterFilter | stringA filter over this whole drawing: a Filter strategy (Filter.grayscale(), Filter.luminanceToAlpha()) or a raw CSS filter string ("blur(2px)", "url(#shadow)").
keystringInternal per-node key override.
textstring | FieldExprRequired. Text content (raw channel — a literal, field name, or accessor).
fillstring | FieldExpr"black"Fill color, or a field name for a color scale.
strokestring | FieldExprStroke color.
strokeWidthnumber0Stroke width in pixels.
fontSizenumber12Font size in pixels.
fontFamilystring"system-ui, sans-serif"Font family.
fontStylestringRaw CSS font-style (e.g. "italic").
fontWeightnumber | stringCSS font-weight (e.g. 300, 700, "bold").
debugBoundingBoxbooleanfalseDraw the text's bounding box, for layout debugging.
rotatenumber0Rotation 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 ​

OptionTypeDefaultDescription
xnumber | string | FieldExprLeft edge position.
cxnumber | string | FieldExprCenter x.
x2number | string | FieldExprRight edge position.
wnumber | string | FieldExprWidth.
emXbooleanEmbed x in the parent's x space.
ynumber | string | FieldExprStart edge on y: the top edge where y reads top-down, the bottom edge where it grows upward.
cynumber | string | FieldExprCenter y.
y2number | string | FieldExprOther y edge position.
hnumber | string | FieldExprHeight.
emYbooleanEmbed y in the parent's y space.
dimsRecord<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 ​

ts
// 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 }))