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.
ris the radius, so the diameter is2rfor every kind of value. A datarsizes both axes.areais 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 dataareasizes both axes.worhis the diameter along that axis. The other axis takes the same length, so a dataworhsizes both axes at one scale. Where the circle is placed at a data value on the other axis (ascatterwith onlyx), 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.
| Option | Type | Default | Description |
|---|---|---|---|
filter | Filter | string | A filter over this whole drawing: a Filter strategy (Filter.grayscale(), Filter.luminanceToAlpha()) or a raw CSS filter string ("blur(2px)", "url(#shadow)"). | |
r | number | string | FieldExpr | Radius. 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. | |
area | number | string | FieldExpr | Area. 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. | |
fill | string | FieldExpr | Fill color, or a field name for a color scale. | |
stroke | string | FieldExpr | Stroke color. Defaults to fill. | |
strokeWidth | number | 0 | Stroke width in pixels. |
opacity | number | string | FieldExpr | 1 | Opacity, 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). |
fillOpacity | number | Opacity of the fill alone, 0 to 1. The stroke keeps opacity. | |
debug | boolean | Dev-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
| Option | Type | Default | Description |
|---|---|---|---|
x | number | string | FieldExpr | Left edge position. | |
cx | number | string | FieldExpr | Center x. | |
x2 | number | string | FieldExpr | Right edge position. | |
w | number | string | FieldExpr | Width. | |
emX | boolean | Embed x in the parent's x space. | |
y | number | string | FieldExpr | Start edge on y: the top edge where y reads top-down, the bottom edge where it grows upward. | |
cy | number | string | FieldExpr | Center y. | |
y2 | number | string | FieldExpr | Other y edge position. | |
h | number | string | FieldExpr | Height. | |
emY | boolean | Embed y in the parent's y space. | |
dims | Record<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) }))