text

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

from gofish import chart, text

chart([{"label": "GoFish"}]).mark(
    text(text="label", font_size=28, fill="steelblue")
).render(w=240, h=80)

Signature

text(*, text=None, fill=None, stroke=None, stroke_width=None, filter=None,
     font_size=None, font_family=None, font_style=None, font_weight=None,
     debug_bounding_box=None, rotate=None, text_anchor=None,
     x=None, cx=None, x2=None, w=None, em_x=None,
     y=None, cy=None, y2=None, h=None, em_y=None,
     dims=None, key=None) -> Mark

Keyword-only (matches every existing call site, which already passes text=... by keyword).

Parameters

A text label. Box geometry via the shared dims channels positions the text anchor.

Option	Type	Default	Description
key	str		Internal per-node key override.
text	str		Required. Text content (raw channel — a literal, field name, or accessor).
fill	str	"black"	Fill color, or a field name for a color scale.
stroke	str		Stroke color.
stroke_width	float	0	Stroke width in pixels.
filter	str		Raw SVG filter attribute.
font_size	float	12	Font size in pixels.
font_family	str	"system-ui, sans-serif"	Font family.
font_style	str		Raw CSS font-style (e.g. "italic").
font_weight	float | str		CSS font-weight (e.g. 300, 700, "bold").
debug_bounding_box	bool	False	Draw the text's bounding box, for layout debugging.
rotate	float	0	Rotation in degrees, clockwise on screen, about the text anchor.
text_anchor	str	"start"	Where the text anchor — the local origin rotate pivots about and dims channels position — sits along the string: its first character, center, or last character.

Box dimensions

Option	Type	Default	Description
x	int | float | str		Left edge position.
cx	int | float | str		Center x.
x2	int | float | str		Right edge position.
w	int | float | str		Width.
em_x	bool		Embed x in the parent's x space.
y	int | float | str		Start edge on y: the top edge where y reads top-down, the bottom edge where it grows upward.
cy	int | float | str		Center y.
y2	int | float | str		Other y edge position.
h	int | float | str		Height.
em_y	bool		Embed y in the parent's y space.
dims	dict		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}.

Returns a Mark for use in .mark().

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 text_anchor point: the left edge for the default "start" (as for a rect), the center for "middle", the right edge for "end".

rotate turns the glyphs about the point on their baseline at text_anchor; the box is then the rotated glyphs' footprint.

Encoding

The text option takes a constant, a field name (a string column in your data), or a callable (row) -> str evaluated per row:

text(text="Hello")               # constant string
text(text="name")                # content from a field
text(text=lambda row: f"{row['amount']}%")  # computed per row

Examples

# Static label
chart([{"label": "GoFish"}]).mark(text(text="label", font_size=24, fill="steelblue"))

# 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(select_all("bars"))
        .flow(group(by="lake"))
        .mark(lambda d: spread(
            [d[0], text(text=str(sum(r["count"] for r in d[0].datum)))],
            dir="y", alignment="middle", spacing=10,
        )),
])

# Computed per-row label
chart(bottles).mark(text(text=lambda d: f"{d['amount']}%", font_size=35, fill="#666"))

# Italic label
text(text="note", font_style="italic")

# Light-weight label
text(text="caption", font_weight=300)