Skip to content

circle ​

Draws a circle for each data item. It is an ellipse locked to a 1:1 aspect ratio, and it takes the same box dimensions.

The diameter is set by at most one of r, area, w, or h. A number is pixels (square pixels for area), and a field name, field(...), or accessor is data.

  • r is the radius, so the diameter is 2r for every kind of value. A data r sizes both axes.
  • area is the circle's area. It is an area channel: it sums the mark's rows and hands the circle the square root of the sum, so the area, not the radius, is proportional to the value. A data area sizes both axes.
  • w or h is the diameter along that axis. The other axis takes the same length, so a data w or h sizes both axes at one scale. Where the circle is placed at a data value on the other axis (a scatter with only x), the other axis follows it in pixels and takes no room there.

With none of them, the circle fills the space it is given. Passing more than one is an error.

js
gf.chart([{ size: 40 }])
  .mark(gf.circle({ r: 40, fill: "coral" }))
  .render(root, { w: 150, h: 150 });

Signature ​

ts
circle({ r?, area?, w?, h?, x?, cx?, x2?, y?, cy?, y2?, emX?, emY?, dims?,
         fill?, stroke?, strokeWidth?, opacity?, fillOpacity?, debug? })

Parameters ​

A circle: an ellipse locked to a 1:1 aspect ratio, with the same box dimensions. Its size is set by at most one of r, area, w, or h and applies to both axes; with none, the circle fills the space it is given.

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)").
rnumber | string | FieldExprRadius. The diameter is 2r for a number (pixels), a field name, or an accessor alike. Pass at most one of r, area, w, and h.
areanumber | string | FieldExprArea. A number is square pixels. A field name or an accessor is data, summed over the mark's rows, and the circle's area is proportional to it, so its radius grows with the square root. Pass at most one of r, area, w, and h.
fillstring | FieldExprFill color, or a field name for a color scale.
strokestring | FieldExprStroke color. Defaults to fill.
strokeWidthnumber0Stroke width in pixels.
opacitynumber | string | FieldExpr1Opacity, 0 to 1, applied to fill and stroke: a number, a field name, or a per-datum accessor (in JS also a live(...) value, which does not cross the wire).
fillOpacitynumberOpacity of the fill alone, 0 to 1. The stroke keeps opacity.
debugbooleanDev-only flag: logs this mark's key and datum to the console as it is built. It changes nothing about what is drawn.

Box dimensions ​

OptionTypeDefaultDescription
xnumber | string | FieldExprLeft edge position.
cxnumber | string | FieldExprCenter x.
x2number | string | FieldExprRight edge position.
wnumber | string | FieldExprWidth.
emXbooleanEmbed x in the parent's x space.
ynumber | string | FieldExprStart edge on y: the top edge where y reads top-down, the bottom edge where it grows upward.
cynumber | string | FieldExprCenter y.
y2number | string | FieldExprOther y edge position.
hnumber | string | FieldExprHeight.
emYbooleanEmbed y in the parent's y space.
dimsRecord<string, AxisDimsValue>Box dimensions by axis name: x/y, or a name the enclosing coordinate space declares (polar theta/r, geo lon/lat). Each value is a position (like x) or an interval {min, center, max, size, embedded}.

Examples ​

ts
// Fixed size circle
.mark(circle({ r: 10, fill: "steelblue" }))

// Circle with stroke
.mark(circle({ r: 15, fill: "white", stroke: "black", strokeWidth: 2 }))

// Bubble chart: the radius encodes a field
.mark(circle({ r: "population", fill: "region" }))

// Area proportional to a field, one circle per lake
.mark(circle({ area: "count", fill: "lake" }))

// Radius from an accessor
.mark(circle({ r: (d) => (d.highlight ? 6 : 3) }))

// Diameter read against the y axis
.mark(circle({ h: "value" }))

// Named for use with selectAll()
.mark(circle({ r: 8 }).name("points"))

// Per-datum opacity: fade everything but the current day
.mark(circle({ r: 3, fill: "species", opacity: (d) => (d.day === day() ? 1 : 0.1) }))