Charts

Creating a chart

Create a chart with Datum.chart(). Thetarget option identifies the element where the chart will be rendered, while datum contains the visualization layers that make up the chart.

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

const values = [
    18,
    24,
    21,
    32,
    28,
    38,
    42
];

Datum.chart({
    target: '#charts-basic',
    title: 'Weekly activity',
    subtitle: 'Sessions over the last seven days',
    caption: 'Example data',
    height: 320,

    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',
            radius: 4
        })
    ]
});

Target

The target option can be a CSS selector or an existing DOM element.

Datum.chart({
    target: '#chart',
    datum: [...]
});

Datum creates its chart container and SVG inside the target element.

Layers

The datum option is an array of visualization layers. Multiple layers can share the same chart surface and coordinate system.

datum: [
    Datum.area(values, {...}),
    Datum.line(values, {...}),
    Datum.dot(values, {...})
]

This composition model allows different visual representations of the same or related data to be combined into a single chart.

Size

Use width and height to control the chart dimensions.

Datum.chart({
    target: '#chart',
    width: 800,
    height: 400,
    datum: [...]
});

When a numeric width is not supplied, Datum measures the available width of the chart container. The default fallback width is 600 pixels and the default height is 360 pixels.

Chart text

Charts can include a title, subtitle and caption.

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

    title: 'Weekly activity',
    subtitle: 'Sessions over the last seven days',
    caption: 'Example data',

    datum: [...]
});

Automatic layout

Datum calculates the chart plot area from the data and configured layers. Axis spacing and padding are adjusted automatically to accommodate labels, ticks and legends.

Bar, histogram, candlestick and heatmap layers use band-based horizontal positioning, while continuous layers such as lines and areas are positioned across the available plot width.

Configuration

Set the chart-level resize: true option to redraw when its container width changes. The configured height stays fixed (360 by default). Updates are batched per animation frame and ignore subpixel width changes. Entrance animations run only on initial render, and legend selections survive resizing. Callchart.destroy() to disconnect the observer and remove a responsive chart when it is no longer needed.

const chart = Datum.chart({
    target: '#chart',
    height: 380,
    resize: true,
    datum: [Datum.line(values)]
});

Set config.xAxis.min and config.xAxis.maxto limit the X-axis. Numeric X categories and scatter charts use numeric values; text categories use zero-based category positions. Either bound may be omitted for automatic scaling. Bounds must be finite numbers, with min less than max. Marks outside the plot are clipped. Pie charts do not use these bounds.

config: {
    xAxis: { min: 1, max: 20 },
    yAxis: { min: 0, max: 100 }
}

Set config.yAxis.min and config.yAxis.maxto fix the numeric Y-axis bounds. Either bound may be omitted to retain automatic scaling for that side. Explicit bounds override padding and the automatic zero baseline; marks outside the bounds are clipped to the plot. These options apply to Cartesian charts, rather than pie charts or categorical heatmap axes.

Datum.chart({
    target: '#chart',
    config: {
        yAxis: { min: 0, max: 100 }
    },
    datum: [Datum.line(values)]
});

Bounds must be finite numbers, with min less thanmax when both are supplied.

Additional chart behavior is configured through theconfig object.

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

    config: {
        padding: {
            top: 24,
            right: 24,
            bottom: 36,
            left: 36
        },

        xAxis: {
            labelAngle: 0,
            interval: 1
        }
    },

    datum: [...]
});

Datum automatically calculates padding when individual values are not supplied.

Animation

Set animated to true to enable chart animation.

Datum.chart({
    target: '#chart',
    animated: true,
    animationDelay: '40ms',
    datum: [...]
});

animationDelay accepts a millisecond value such as '40ms' or '200ms'.

Tooltips

Tooltips are enabled by default. Settooltip to false when a chart should not display interactive tooltip information.

Datum.chart({
    target: '#chart',
    tooltip: false,
    datum: [...]
});