17 Edge Reference

See Drawing Edges for the narrative version and the curve control figure.

17.1 `edge()`

typ.edge(
  ..waypoints,
  from: auto, to: auto, bend: 0,
  highlight: auto, label: none, label-pos: 0.5,
  stroke: auto, clip: auto, preset: none,
  style: (:), base-style: (:),
)

At least two waypoints. A waypoint may be a node value, a typ.port(..), an coordinate pair (x, y), a typ.offset(point, dx, dy), a typ.ref(name), a typ.rel(dx, dy) (not in first position), a typ.smooth(waypoint) (interior only), or a typ.line/typ.quad/ typ.cubic path element. More than two waypoints form one continuous path. A multi-item fragment isn’t a valid endpoint — pass its constructor result directly, or its nodes as separate waypoints.

Deferred/reference forms
`typ.rel(dx, dy)`	Offset from the preceding resolved waypoint.
`typ.ref(name)`	Looks up a node emitted elsewhere by name; doesn’t emit it. `name` must be a string.
`typ.offset(point, dx, dy)`	Offset from an explicit point, in numeric diagram units; also usable for node/content placement.

Coordinate pairs may contain deferred .x/.y projections. Explicit offset/projected points do not clip to their source nodes; normal node and ref endpoints retain automatic clipping. Bézier control points still require numeric coordinates.

17.2 Curve controls

Form	Effect
`bend: 0.4`	Signed perpendicular offset (diagram units) on each plain segment.
`smooth(waypoint)`	Marks an interior waypoint as a quadratic Bézier guide; consecutive guides form one tangent-continuous run.
`from: dir, to: dir`	Outward handle from the first/last endpoint of a simple two-waypoint edge. `dir` is an angle, `left`/`right`/`top`/`bottom`, or `(direction, positive-strength)`.
`line(end)`	Explicit straight segment.
`quad(control, end)`	Explicit quadratic Bézier segment.
`cubic(control-start, control-end, end)`	Explicit cubic Bézier segment.

bend:, smooth(), and from:/to: are mutually exclusive on one edge. Explicit path elements can’t combine with smooth() on the same edge.

17.3 Clipping

clip: true (default) trims node endpoints to the true resolved silhouette — circle, ellipse, rounded rectangle, polygon. Coordinates/ports need no trim. from:/to: build directly from the selected boundary anchor. Other curved endpoints split at a detected outline intersection: straight segments analytically against polygon edges, curved ones via bounded sampling plus physical-accuracy refinement (an excursion entirely between two samples is below that search’s detection guarantee). clip: false skips all outline work and uses raw node-centre endpoints.

17.4 Style keys

typ.edge-defaults  // ==
(
  stroke: stroke(paint: black, thickness: 0.55pt, cap: "butt", join: "miter"),
  highlight: none,
  highlight-width: 4pt,
  highlight-offset: 0pt,
  highlight-opacity: 100%,
  label-size: auto,
  label-offset: 0pt,
  label-fill: white,
  label-inset: 1.5pt,
  clip: true,
)

Key	Contract
`stroke`	Native Typst stroke value.
`highlight`	`none`, one colour, or a zero/one/two-colour array. `()` explicitly clears a lower-precedence highlight. One colour normalizes to `(colour, colour)`.
`highlight-width`, `highlight-offset`, `highlight-opacity`	Tune the highlight bands; butt caps, mitered joins, same as the default wire stroke.
`label-size`	`auto` (inherits diagram label size) or a length.
`label-offset`	Perpendicular offset from the local wire direction.
`label-fill`	Knockout fill behind the label; native paint value.
`label-inset`	Padding around the label’s knockout; accepts the relative lengths and side dictionaries Typst boxes accept.
`clip`	Boolean.

Edge style dictionaries are closed: an unknown key is always an error. Direct arguments’ auto (stroke:, and by convention highlight:/clip: too) means “don’t override the resolved style” — auto is not itself a valid value for highlight/clip inside a style: dictionary.

Stroke thickness and the geometric label/highlight lengths support em, resolved against surrounding text before edge zoom; see Font-relative lengths.

Diagram bounds conservatively include square caps on diagonal wires, plus both the displaced centerlines and mitered strokes of highlight bands. Curved highlights are sampled polylines and need this join allowance even for a single Bézier segment. Multi-segment/curved highlighted edges can therefore reserve extra whitespace; the bounds are not an exact ink crop.

17.5 Precedence

typ.edge-defaults
  -> theme.edge-defaults
  -> edge-type base-style
  -> theme.edge-presets[preset]
  -> diagram(edge-styles: (...))
  -> edge(style: (...))
  -> direct stroke:/highlight:/clip:

17.6 Reusable constructors and named presets

typ.edge-type(preset, base-style: (:))

preset is none or a string, positional — the edge-side counterpart to node-type(kind, ..). Forwards every normal edge() argument. A theme that defines named edge presets typically gives each a direct constructor built with edge-type() this way — see typograph-zx’s presets for a worked example. The generic form remains available for a dynamically selected preset: typ.edge(a, b, preset: "some-preset").

17.7 Limitations

A node referenced only by ref(..) must also be emitted as its own statement elsewhere in the diagram — the reference cannot manufacture its target (see Core Concepts).

17.1 edge()