16 Edge Reference

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

16.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 absolute numeric (x, y), 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.

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

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

16.4 Style keys

typ.edge-defaults  // ==
(
  stroke: stroke(paint: black, thickness: 0.55pt, cap: "butt", join: "miter"),
  highlight: none,
  highlight-width: 3pt,
  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.

16.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:

16.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").

16.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).

16.1 edge()