Text

A label is a pin with a text: it has a position, a direction, and a value that holds the text. Everything you know about points and pins applies, so you place a label like any other point.

Placing labels

const handle = canvas.handles.disk("handle", [200, 150])

// Follows the point it is created at
canvas.text.labelAt("here", handle, "label")

// Or attach it, with a fixed offset: 22 px above the handle
const name = canvas.text.label("A", "caption")
Attach.pointToPoint(name, handle, { offset: [0, -22] })
  • canvas.text.label(text, style) creates a label at (0, 0). Place it yourself, with a helper or an attachment.
  • canvas.text.labelAt(text, point, style) puts it on a point and keeps it there: it follows the point when it moves.
  • label.value = "…" changes the text, like any string value.

The text starts at the label’s position. Where it sits relative to that point is a matter of CSS: text-anchor: middle centers it, dominant-baseline: central centers it vertically.

Turning

A label’s text runs along the label’s direction. As long as that is (1, 0), the default, the text is horizontal. Turn the label, and the text turns with it:

Drag the handles. The label sits in the middle of the line and looks at the right handle.
// A label is a pin with a text: it runs along the pin's direction
const label = canvas.text.label("reads along the line", "label centered")
Reactive.do([base, tip], () => {
    Pins.placeAt(label, Points.midPoint(base, tip), label)
    Pins.lookAt(label, tip, label)
})

Turn the line past the vertical, and the text doesn’t end up upside down: it flips to stay readable. That’s auto-flip, on by default. The long forms of label and labelAt switch it off, and they also take a fixed extra angle and an offset from the anchor: labelAt(text, point, oriented, angle, offset, autoFlip, style). With oriented = false a label stays horizontal whatever its direction.

Text along a path

canvas.text.labelAlongPolyline(text, polyline, style) writes the text along a polyline and keeps it there when the polyline changes. The long form adds an offset from the line, and a flag to flip the text to the other side:

Drag the corners of the path. The text is 10 px above it.
const path = canvas.visuals.polyline("line", [
    canvas.handles.disk("handle", [80, 220]),
    canvas.handles.disk("handle", [260, 90]),
    canvas.handles.disk("handle", [420, 200]),
    canvas.handles.disk("handle", [580, 80]),
])
canvas.text.labelAlongPolyline("a label that follows the path as it bends", path, 10, false, "label")

Styling text

Labels are SVG text elements, styled with CSS like everything else: font, fill for the color, text-anchor and dominant-baseline for the alignment. A text’s size is in pixels of its group, so a scaled group scales its text too.

For text that changes over time, see Animate.string.animate: it types a new text letter by letter.