Ruler

Basic usage

Create a ruler with Datum.ruler() and provide the reference value using value.

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

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

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

    datum: [
        Datum.line(values, {
            name: 'Sessions',
            stroke: Color.Blue,
            strokeWidth: 2
        }),

        Datum.dot(values, {
            stroke: Color.Blue,
            fill: '#ffffff',
            strokeWidth: 2,
            radius: 4
        }),

        Datum.ruler([], {
            value: 25,
            stroke: Color.Red,
            strokeWidth: 2,
            dashed: true
        })
    ]
});

Syntax

Datum.ruler(data, {
    direction,
    value,
    stroke,
    strokeWidth,
    dashed,
    dashArray
});

Rulers generally do not require their own dataset, so an empty array can be passed as the first argument.

Datum.ruler([], {
    value: 25
});

Horizontal rulers

Rulers are horizontal by default. The suppliedvalue is positioned against the chart's Y scale and the line extends across the plot area.

Datum.ruler([], {
    value: 25,
    stroke: Color.Red
});

You can also explicitly specify the horizontal direction.

Datum.ruler([], {
    direction: 'horizontal',
    value: 25
});

Vertical rulers

Set direction to 'vertical' to draw a reference line along the X axis.

Datum.ruler([], {
    direction: 'vertical',
    value: 3,
    stroke: Color.Red
});

Stroke

Use stroke to control the ruler color andstrokeWidth to control its thickness.

Datum.ruler([], {
    value: 25,
    stroke: Color.Red,
    strokeWidth: 2
});

Dashed rulers

Set dashed to true to display the ruler as a dashed line.

Datum.ruler([], {
    value: 25,
    stroke: Color.Red,
    dashed: true
});

The dash pattern can be customized usingdashArray.

Datum.ruler([], {
    value: 25,
    dashed: true,
    dashArray: '8 4'
});

Options

{
    direction: 'horizontal',
    value: 0,
    stroke: '#9ca3af',
    strokeWidth: 1.5,
    dashed: false,
    dashArray: '4 4'
}

Composing with other layers

Rulers are most useful when composed with data layers. For example, a ruler can indicate a target value across a line chart.

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

    datum: [
        Datum.line(values, {
            stroke: Color.Blue
        }),

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

        Datum.ruler([], {
            value: 25,
            stroke: Color.Red,
            dashed: true
        })
    ]
});