D3

Areas ​

Examples · The area generator produces an area defined by a topline and a baseline as in an area chart. Typically, the two lines share the same x-values (x0 = x1), differing only in y-value (y0 and y1); most commonly, y0 is defined as a constant representing zero (the y scale’s output for zero). The topline is defined by x1 and y1 and is rendered first; the baseline is defined by x0 and y0 and is rendered second with the points in reverse order. With a curveLinear curve, this produces a clockwise polygon. See also radial areas.

area(x, y0, y1) ​

Source · Constructs a new area generator with the given x, y0, and y1 accessors or numbers.

js
const area = d3.area((d) => x(d.Date), y(0), (d) => y(d.Close));

If x, y0 or y1 are not specified, the respective defaults will be used. The above can be expressed more explicitly as:

js
const area = d3.area()
    .x((d) => x(d.Date))
    .y0(y(0))
    .y1((d) => y(d.Close));

area(data) ​

Source · Generates an area for the given array of data.

js
svg.append("path").attr("d", area(data));

If the area generator has a context, then the area is rendered to this context as a sequence of path method calls and this function returns void. Otherwise, a path data string is returned.

CAUTION

Depending on this area generator’s associated curve, the given input data may need to be sorted by x-value before being passed to the area generator.

area.x(x) ​

Source · If x is specified, sets x0 to x and x1 to null and returns this area generator.

js
const area = d3.area().x((d) => x(d.Date));

If x is not specified, returns the current x0 accessor.

js
area.x() // (d) => x(d.Date)

area.x0(x) ​

TIP

This method is intended for vertically-oriented areas, as when time goes down↓ rather than right→; for the more common horizontally-oriented areas, use area.x instead.

Source · If x is specified, sets the x0 accessor to the specified function or number and returns this area generator.

js
const area = d3.area().x0(x(0));

When an area is generated, the x0 accessor will be invoked for each defined element in the input data array, being passed the element d, the index i, and the array data as three arguments.

If x is not specified, returns the current x0 accessor.

js
area.x0() // () => 20

The x0 accessor defaults to:

js
function x(d) {
  return d[0];
}

The default x0 accessor assumes that the input data are two-element arrays of numbers [[x0, y0], [x1, y1], …]. If your data are in a different format, or if you wish to transform the data before rendering, then you should specify a custom accessor as shown above.

area.x1(x) ​

TIP

This method is intended for vertically-oriented areas, as when time goes down↓ rather than right→; for the more common horizontally-oriented areas, use area.x instead.

Source · If x is specified, sets the x1 accessor to the specified function or number and returns this area generator.

js
const area = d3.area().x1((d) => x(d.Close));

When an area is generated, the x1 accessor will be invoked for each defined element in the input data array, being passed the element d, the index i, and the array data as three arguments.

If x is not specified, returns the current x1 accessor.

js
area.x1() // (d) => x(d.Close)

The x1 accessor defaults to null, indicating that the previously-computed x0 value should be reused for the x1 value; this default is intended for horizontally-oriented areas.

area.y(y) ​

TIP

This method is intended for vertically-oriented areas, as when time goes down↓ rather than right→; for the more common horizontally-oriented areas, use area.y0 and area.y1 instead.

Source · If y is specified, sets y0 to y and y1 to null and returns this area generator.

js
const area = d3.area().y((d) => y(d.Date));

If y is not specified, returns the current y0 accessor.

js
area.y() // (d) => y(d.Date)

area.y0(y) ​

Source · If y is specified, sets the y0 accessor to the specified function or number and returns this area generator.

js
const area = d3.area().y0(y(0));

When an area is generated, the y0 accessor will be invoked for each defined element in the input data array, being passed the element d, the index i, and the array data as three arguments. For a horizontally-oriented area with a constant baseline (i.e., an area that is not stacked, and not a ribbon or band), y0 is typically set to the output of the y scale for zero.

If y is not specified, returns the current y0 accessor.

js
area.y0() // () => 360

The y0 accessor defaults to:

js
function y() {
  return 0;
}

In the default SVG coordinate system, note that the default zero represents the top of the chart rather than the bottom, producing a flipped (or “hanging”) area.

area.y1(y) ​

Source · If y is specified, sets the y1 accessor to the specified function or number and returns this area generator.

js
const area = d3.area().y1((d) => y(d.Close));

When an area is generated, the y1 accessor will be invoked for each defined element in the input data array, being passed the element d, the index i, and the array data as three arguments.

If y is not specified, returns the current y1 accessor.

js
area.y1() // (d) => y(d.Close)

The y1 accessor defaults to:

js
function y(d) {
  return d[1];
}

The default y1 accessor assumes that the input data are two-element arrays of numbers [[x0, y0], [x1, y1], …]. If your data are in a different format, or if you wish to transform the data before rendering, then you should specify a custom accessor as shown above. A null accessor is also allowed, indicating that the previously-computed y0 value should be reused for the y1 value; this can be used for a vertically-oriented area, as when time goes down↓ instead of right→.

area.defined(defined) ​

Examples · Source · If defined is specified, sets the defined accessor to the specified function or boolean and returns this area generator.

js
const area = d3.area().defined((d) => !isNaN(d.Close));

When an area is generated, the defined accessor will be invoked for each element in the input data array, being passed the element d, the index i, and the array data as three arguments. If the given element is defined (i.e., if the defined accessor returns a truthy value for this element), the x0, x1, y0 and y1 accessors will subsequently be evaluated and the point will be added to the current area segment. Otherwise, the element will be skipped, the current area segment will be ended, and a new area segment will be generated for the next defined point. As a result, the generated area may have several discrete segments.

If defined is not specified, returns the current defined accessor.

js
area.defined() // (d) => !isNaN(d.Close)

The defined accessor defaults to the constant true, and assumes that the input data is always defined:

js
function defined() {
  return true;
}

Note that if an area segment consists of only a single point, it may appear invisible unless rendered with rounded or square line caps. In addition, some curves such as curveCardinalOpen only render a visible segment if it contains multiple points.

area.curve(curve) ​

Source · If curve is specified, sets the curve factory and returns this area generator.

js
const area = d3.area().curve(d3.curveStep);

If curve is not specified, returns the current curve factory, which defaults to curveLinear.

js
area.curve() // d3.curveStep

area.context(context) ​

Source · If context is specified, sets the context and returns this area generator.

js
const context = canvas.getContext("2d");
const area = d3.area().context(context);

If context is not specified, returns the current context.

js
area.context() // context

The context defaults to null. If the context is not null, then the generated area is rendered to this context as a sequence of path method calls. Otherwise, a path data string representing the generated area is returned.

area.digits(digits) ​

Source · If digits is specified, sets the maximum number of digits after the decimal separator and returns this area generator.

js
const area = d3.area().digits(3);

If digits is not specified, returns the current maximum fraction digits, which defaults to 3.

js
area.digits() // 3

This option only applies when the associated context is null, as when this area generator is used to produce path data.

area.lineX0() ​

An alias for area.lineY0.

area.lineY0() ​

Source · Returns a new line generator that has this area generator’s current defined accessor, curve and context. The line’s x-accessor is this area’s x0-accessor, and the line’s y-accessor is this area’s y0-accessor.

area.lineX1() ​

Source · Returns a new line generator that has this area generator’s current defined accessor, curve and context. The line’s x-accessor is this area’s x1-accessor, and the line’s y-accessor is this area’s y0-accessor.

area.lineY1() ​

Source · Returns a new line generator that has this area generator’s current defined accessor, curve and context. The line’s x-accessor is this area’s x0-accessor, and the line’s y-accessor is this area’s y1-accessor.