Area

Basic usage

Create an area layer with Datum.area(). Pass the data as the first argument and area options as the second.

import {
    Datum,
    Color
} from '@psdpainter/datum-js';

const values = [
    14,
    22,
    18,
    30,
    26,
    38,
    34
];

Datum.chart({
    target: '#area-example',
    height: 300,

    datum: [
        Datum.area(values, {
            name: 'Sessions',
            fill: Color.Blue,
            opacity: 0.35,
            gradient: true,
            smooth: true,
            tension: 0.2
        })
    ]
});

Syntax

Datum.area(data, {
    x,
    y,
    fill,
    opacity,
    gradient,
    smooth,
    tension,
    name,
    tooltip
});

Datum.area() creates a layer definition that can be included in the datum array passed toDatum.chart().

Data keys

Area layers use x and y as their default data-property names. Use the corresponding options when your objects use different property names.

const sales = [
    { month: 'Jan', revenue: 18 },
    { month: 'Feb', revenue: 26 },
    { month: 'Mar', revenue: 22 }
];

Datum.area(sales, {
    x: 'month',
    y: 'revenue'
});

Numeric arrays are also supported. Datum assigns sequential X categories beginning at 1.

Fill

Use fill to control the color of the area. When no fill is supplied, Datum selects a color from its default area palette.

Datum.area(values, {
    fill: Color.Blue
});

Opacity

Use opacity to control the transparency of the filled area. The default value is 0.25.

Datum.area(values, {
    fill: Color.Blue,
    opacity: 0.35
});

Gradient

Set gradient to true to replace the solid fill with a vertical gradient based on the area's fill color.

Datum.area(values, {
    fill: Color.Blue,
    opacity: 0.35,
    gradient: true
});

The gradient begins with the configured fill color and opacity and fades vertically toward transparency.

Smoothing

Area boundaries use straight segments by default. Setsmooth to true to create a smooth cubic Bézier boundary between points.

Datum.area(values, {
    smooth: true
});

Tension

The tension option controls the shape of the smoothed boundary. Its default value is 0.2and only affects the area when smooth is enabled.

Datum.area(values, {
    smooth: true,
    tension: 0.2
});

Series name

Use name to provide a meaningful label for the area series. Datum uses the name when displaying the layer in the chart legend.

Datum.area(values, {
    name: 'Sessions',
    fill: Color.Blue
});

Tooltips

Area layers participate in the chart's shared tooltip and crosshair interaction by default.

Set tooltip to false to exclude the layer from tooltip interaction.

Datum.area(values, {
    tooltip: false
});

Options

{
    x: 'x',
    y: 'y',
    fill: undefined,
    opacity: 0.25,
    gradient: false,
    smooth: false,
    tension: 0.2,
    name: undefined,
    tooltip: undefined
}

Composing with other layers

Area layers are commonly placed behind line and dot layers. Because Datum renders layers in array order, placing the area first allows the line and points to render above it.

Datum.chart({
    target: '#chart',

    datum: [
        Datum.area(values, {
            fill: Color.LightBlue,
            opacity: 0.2
        }),

        Datum.line(values, {
            stroke: Color.Blue,
            strokeWidth: 2
        }),

        Datum.dot(values, {
            stroke: Color.Blue,
            fill: '#ffffff'
        })
    ]
});