Text Basics

Use Text for labels, captions, annotations, and chart typography. Text is an SVG element, so it uses the same attribute model as shapes.

Placing Text

Create text with content and place it with x and y or pos.

import pydreamplet as dp

svg = dp.SVG(540, 360)

title = dp.Text(
    "pyDreamplet",
    x=svg.w / 2,
    y=92,
    fill="currentColor",
    font_size=44,
    font_weight=700,
    text_anchor="middle",
)

svg.append(title)

The x and y attributes define the text anchor point, not the top-left corner of a text box.

Alignment

Use text_anchor for horizontal alignment and alignment_baseline for vertical alignment.

center = dp.G(pos=(svg.w / 2, svg.h / 2))
svg.append(center)

center.append(dp.Circle(cx=0, cy=0, r=86, fill="#14b8a6", opacity=0.18))
center.append(dp.Line(-110, 0, 110, 0, stroke="currentColor", opacity=0.35))
center.append(dp.Line(0, -70, 0, 70, stroke="currentColor", opacity=0.35))

center.append(
    dp.Text(
        "centered",
        x=0,
        y=0,
        fill="currentColor",
        font_size=26,
        text_anchor="middle",
        alignment_baseline="middle",
    )
)

For labels next to marks, change the anchor instead of manually estimating text width.

center.append(
    dp.Text(
        "start",
        x=102,
        y=0,
        fill="#f83898",
        font_size=18,
        text_anchor="start",
        alignment_baseline="middle",
    )
)

Multiline Text

Text accepts newline characters. Use v_space to control the vertical spacing between lines.

note = dp.Text(
    "vector graphics\nwith code",
    x=svg.w / 2,
    y=292,
    fill="currentColor",
    font_size=20,
    text_anchor="middle",
    v_space=26,
)

svg.append(note)

Measuring Text

When layout depends on text dimensions, use TypographyMeasurer. It can read font properties from a Text element.

from pydreamplet.typography import TypographyMeasurer

label = dp.Text(
    "Measured label",
    font_family="Arial",
    font_size=18,
    font_weight=400,
)

measurer = TypographyMeasurer()
width, height = measurer.measure_text(label)

Measurements are layout estimates. Browser rendering can differ slightly between operating systems, fonts, and SVG viewers.

Measured Layout

Use the measured width and height to align other elements around a label. This example draws a rectangle centered on text whose anchor is also centered.

from pydreamplet.typography import TypographyMeasurer, get_system_font_path

font_path = get_system_font_path("Arial", 700)
if font_path is None:
    raise RuntimeError("Arial is not available on this system.")

label = dp.Text(
    "pyDreamplet",
    x=0,
    y=0,
    font_family="Arial",
    font_size=42,
    font_weight=700,
    fill="currentColor",
    text_anchor="middle",
    alignment_baseline="middle",
)

width, height = TypographyMeasurer(font_path=font_path).measure_text(label)

group = dp.G(pos=(svg.w / 2, svg.h / 2))
group.append(
    dp.Rect(
        x=-width / 2,
        y=-height / 2,
        width=width,
        height=height,
        fill="none",
        stroke="#14b8a6",
        stroke_width=2,
    ),
    label,
)
svg.append(group)