Skip to content

line ​

Connects data points center-to-center with a line. Takes the array of refs returned by selectAll().

js
const locations = Object.entries(lakeLocations).map(([lake, { x, y }]) => ({
  lake,
  x,
  y,
}));

gf.layer([
  gf
    .chart(locations)
    .flow(gf.scatter({ by: "lake", x: "x", y: "y" }))
    .mark(gf.blank().name("points")),
  gf
    .chart(gf.selectAll("points"))
    .mark(gf.line({ stroke: "steelblue", strokeWidth: 2 })),
]).render(root, { w: 400, h: 250, axes: true });

Signature ​

ts
line({ stroke?, strokeWidth = 1, strokeDasharray?, opacity?, curve?, along?, from?, to?, w?, h?, emX?, emY? })

Parameters ​

Center-mode connector — the path between the centers of consecutive marks (the drop-in for the removed connect). Bag form over a ref array, or pairwise {from, to} form over rows with two ref columns.

OptionTypeDefaultDescription
filterFilter | stringA filter over this whole drawing: a Filter strategy (Filter.grayscale(), Filter.luminanceToAlpha()) or a raw CSS filter string ("blur(2px)", "url(#shadow)").
fillstring | FieldExprA line's path is never filled. fill is the channel the shared color scale reads: a field name or an accessor colors each line by group (it must be constant within the line), and it is the line color when stroke is omitted.
strokestring | FieldExprLine color, or a field name or accessor for a color scale (constant within the line). Defaults to fill.
strokeWidthnumber1Line thickness in pixels.
strokeDasharraystringRaw SVG stroke-dasharray (e.g. "12") for a dashed line.
opacitynumberOpacity, 0 to 1.
blendMode"normal" | "multiply" | "screen" | "overlay" | "color" | "luminosity""normal"How connectors mix where they overlap (CSS mix-blend-mode).
curveCurveScreen-space path shape, made by a call in the Curve family: Curve.linear(), Curve.step(), Curve.monotone(), Curve.smooth(), Curve.catmullRom(), Curve.bezier(), Curve.orthogonal({bend}), Curve.arc({direction}) or Curve.perfectArrows({bow, ...}). Curve.step(), Curve.linear(), Curve.monotone() and Curve.smooth() are read over the parameter of the run, from the least to the most smooth. Curve.step() holds every value that depends on the ordering field until the next point, then jumps: a staircase when the ordering field is an axis (a line chart over years), and straight jumps between the points when it is not (a connected scatter plot). Curve.monotone() is piecewise monotone: between two neighboring points each coordinate only rises or only falls, so the curve never goes past either point. It does not make the whole line monotone: the line still turns where the data turns, and the turn sits exactly on the data point. For a path in x and y (a connected scatter plot) this holds for x and y separately, over the ordering field. It is the same curve as d3 curveMonotoneX and Vega-Lite interpolate "monotone". Curve.smooth() rounds a peak a little past its point, but keeps a run of equal values flat. Curve.catmullRom() is a centripetal Catmull-Rom through the points on screen. It can overshoot between points, and it is not used when reading values over time (a mark moving along the run follows a data-space curve). Omitted, it is Curve.monotone() on a homogeneous continuous connection axis, else Curve.linear().
dir"x" | "y"Connection axis.
sourceanyAnchor-mode start point: a normalized [fx, fy] on the mark's bbox, or a start/middle/end keyword.
targetanyAnchor-mode end point; see source.
fromstringPairwise form: column holding the source ref.
tostringPairwise form: column holding the target ref.
alongstringNames a flow tier by its by field: that tier becomes the path tier (threading its groups in order) and every OTHER grouping tier splits. Omitted: the path tier is inferred from the flow shape. Naming a field that matches no tier, or using along where the mark doesn't fuse over this chart's own flow (a refs bag, or the pairwise from/to form), is an error.
emXbooleanBlank-fusion anchor key: placed directly in .mark() position, line(opts) elaborates to an invisible anchor tier (a blank() carrying just {w, h, emX, emY}) plus this connector — see the mark construct's doc. Ignored by line itself.
emYbooleanBlank-fusion anchor key — see emX. Ignored by line itself.
wnumber | string | FieldExprBlank-fusion anchor key — see emX. Ignored by line itself.
hnumber | string | FieldExprBlank-fusion anchor key — see emX. Ignored by line itself.

curve takes a member of the Curve family, such as Curve.monotone() or Curve.orthogonal({ bend: "auto" }). When curve is omitted, line inspects the connected points. If they share a continuous connection axis, it smooths them with Curve.monotone(). Otherwise it draws a straight polyline, Curve.linear(). The Curve page compares the curves and says how a line picks the knots of its curve.

Two forms ​

  • Bag form — line() over a GoFishRef[] (e.g. selectAll()): one polyline through all the refs (the example above).
  • Pairwise form — line({ from, to }) over rows whose from/to columns hold refs: one segment per row. Use after resolve has turned an edge table's endpoint ids into node refs — this is how node-link edges are drawn. See .layer() for the full recipe.

Default grouping ​

A line fused into a flow — in .mark() position or as .layer() sugar over the previous tier's marks — splits at the flow's own grouping by default: one tier lays the line's path, and every other grouping in the flow splits it into separate lines. You don't restate the split — the flow one line up already declared it, and line has no option that spells the split directly.

When you need a different path tier than the one inference would pick, name it with along: along: "year" finds the flow tier whose by is "year", makes it the path, and splits by every other grouping tier instead. Naming a field no tier groups by is an error. This doesn't apply to a line drawn over an explicit refs bag (chart(selectAll(...))) or the pairwise { from, to } form — along is only meaningful when the line fuses into a chart's own flow, and throws if used on either of those. A refs bag spells its split structurally instead, with an upstream flow(group({ by: "species" })).

A slope chart is a good example of why the default matters: ten barley varieties across six field sites, one short line per site-variety pair from 1931 to 1932, with no line crossing a site boundary.

ts
chart(barley, { axes: true })
  .flow(
    spread({ by: "site", dir: "x", spacing: 110 }),
    spread({ by: "year", dir: "x", spacing: 36 }),
    scatter({ by: "variety", y: "yield" })
  )
  .mark(line({ stroke: "variety", strokeWidth: 2 }));

No option at all: the innermost tier that lays out the travel axis (the year spread) becomes the path, and every other grouping — site and variety — splits, giving one line per site-variety pair. Writing the same split by hand would take a composite key over both fields; naming it explicitly would be line({ along: "year", stroke: "variety", strokeWidth: 2 }), which picks the same path tier the default already infers.

Sugar: .layer(line(...)) ​

When the line connects a chart's own marks, skip the two-layer selectAll recipe and chain .layer() on the builder with a bare line(...):

ts
chart(data)
  .flow(scatter({ by: "lake", x: "x", y: "y" }))
  .mark(circle({ r: 4, fill: "white", stroke: "black", strokeWidth: 2 }))
  .layer(line({ stroke: "black", strokeWidth: 2 }));

See .layer() for the full semantics, including the zBelow-by-default paint order and the desugaring to the explicit layer([...])

  • selectAll form below (which is still what you want to connect another chart's marks).

Sugar: .mark(line(...)) (blank-fusion) ​

When there's no earlier tier at all — just raw data that needs both fresh anchors and a connector — place line(...) directly in .mark() position and skip .layer() too:

ts
chart(data)
  .flow(scatter({ by: "lake", x: "x", y: "y" }))
  .mark(line({ stroke: "steelblue", strokeWidth: 2 }));

// ...is sugar for the explicit two-tier form:
chart(data)
  .flow(scatter({ by: "lake", x: "x", y: "y" }))
  .mark(blank())
  .layer(line({ stroke: "steelblue", strokeWidth: 2 }));

See .layer()'s blank-fusion section for the full desugaring rule (the {w, h, emX, emY} anchor/connector key split, .name() chaining, and when the rule doesn't fire).

The w/h/emX/emY anchor channels are only meaningful when line gets to synthesize its own anchors this way; passing them to a line that instead connects already-drawn marks (an empty-scope chart() tier inside .layer(), or chart(selectAll(...))/chart(ref(...))) is an error, since there's nothing left for them to anchor.

Example ​

ts
// First chart: bar chart with named layer
chart(data)
  .flow(spread({ by: "x", dir: "x" }))
  .mark(rect({ h: "y" }).name("bars"))
  .render(container, { w: 500, h: 300 });

// Second chart: line over the same bars
chart(selectAll("bars"))
  .mark(line({ stroke: "steelblue", strokeWidth: 2 }))
  .render(container, { w: 500, h: 300 });