HistropediaJS Charts Documentation

Chart Schema new

A chart object renders one timeline-aligned line or area chart with one y-scale and one or more series. Chart points use the same date input shape as articles and time bands.

At a glance: Required fields — id. Each visible line or area needs at least one series with finite point values.

Schema

// Chart Schema (clickable)
{
  id: /* required: number|string */,
  type: /* optional: 'line' | 'area'; default: 'line' */,
  title: /* optional: string */,
  lane: /* optional: number|string */,
  visibility: /* optional: 'visible' (default) | 'hidden' | function(Chart): 'visible' | 'hidden' */,

  series: [
    {
      id: /* optional: number|string */,
      title: /* optional: string */,
      points: [
        {
          date: /* required: DateInput */,
          value: /* required: number|null */
        }
      ],
      style: /* optional: ChartSeriesStyle */
    }
  ],

  scale: {
    source: /* optional: 'data' | 'viewport'; default: 'data' */,
    includeZero: /* optional: boolean; default: false */,
    padding: /* optional: number; default: 0.05 */,
    min: /* optional: number */,
    max: /* optional: number */,
    tickMode: /* optional: 'round' | 'exact'; default: 'round' */,
    tickTarget: /* optional: number; default: 5 */
  },

  typeOptions: {
    area: {
      stacking: {
        active: /* optional: boolean; default: true */,
        interpolation: /* optional: 'linear' | 'step' | 'none'; default: 'linear' */
      }
    }
  },

  area: /* optional: { up?: AreaValue, down?: AreaValue } */,
  style: /* optional: ChartStyle */
};

JavaScript

// Minimal chart
{
  id: "population",
  series: [
    {
      id: "world",
      points: [
        { date: { year: 1990 }, value: 5.3 },
        { date: { year: 2000 }, value: 6.1 },
        { date: { year: 2010 }, value: 6.9 },
        { date: { year: 2020 }, value: 7.8 }
      ]
    }
  ]
}

JavaScript

// Full chart example
{
  id: "energy-mix",
  type: "area",
  title: "Electricity generation",
  lane: "metrics",
  visibility: (chart) => chart.owner.getZoom() >= 30 ? "visible" : "hidden",
  scale: {
    source: "data",
    includeZero: true,
    padding: 0.08,
    tickMode: "round",
    tickTarget: 6
  },
  typeOptions: {
    area: {
      stacking: { active: true, interpolation: "linear" }
    }
  },
  series: [
    {
      id: "renewables",
      title: "Renewables",
      points: [
        { date: { year: 1990 }, value: 19 },
        { date: { year: 2000 }, value: 20 },
        { date: { year: 2010 }, value: 21 },
        { date: { year: 2020 }, value: 29 }
      ],
      style: { color: "#16a34a", area: { opacity: 0.28 } }
    },
    {
      id: "gas",
      title: "Gas",
      points: [
        { date: { year: 1990 }, value: 15 },
        { date: { year: 2000 }, value: 18 },
        { date: { year: 2010 }, value: null },
        { date: { year: 2020 }, value: 23 }
      ],
      style: { color: "#ea580c", lineDash: [6, 4], area: { opacity: 0.2 } }
    }
  ],
  style: {
    legend: { visible: true },
    series: { point: { visible: true, radius: 3 } }
  }
}

`id` number | string

Unique chart identifier. Charts without an id or with a duplicate id are skipped with a warning.

`type` 'line' | 'area'

Use 'line' for stroked series or 'area' for filled area charts. Unknown types are skipped by a runtime guard.

`title` string

Stored on the Chart instance for your own UI. The runtime does not draw a chart title in this release.

`lane` number | string

Lane identifier for lane-scoped charts. If omitted, the chart draws in the main chart area. Unknown lane ids create lanes in the same way lane-scoped article data does.

`visibility` 'visible' | 'hidden' | function

Hide a chart without unloading it, or return visibility from a function receiving the Chart instance.

`series` ChartSeriesData[]

Lines rendered within the chart. All series in one chart share one y-scale.

`series[].id` number | string

Stable series identifier. If omitted, the runtime uses the series index.

`series[].title` string

Legend label. Empty titles are omitted from the legend.

`series[].points` ChartPointData[]

Dated values. Points are normalized and sorted by date before rendering.

`date` DateInput

Point date using the same { year, month, day, precision } shape as articles and time bands. Year-only and month-only dates are accepted.

If precision is supplied, charts use the normalized start boundary for the point position. For example, { year: 2000, precision: 'year' } is plotted at the start of 2000.

`value` number | null

Finite numbers draw points and segments. null, NaN, and infinite values are stored as gaps and break the line.

`series[].style` ChartSeriesStyle

Sparse line and point marker overrides for one series. See Chart Style.

`scale` ChartScaleOptions

Y-scale configuration. Use separate charts when series need different units or independent y-scales.

`scale.source` 'data' | 'viewport'

'data' uses all loaded values. 'viewport' recalculates from values inside the viewport plus finite endpoints of line segments crossing the viewport.

`typeOptions` ChartTypeOptions

Chart-type-specific configuration. For area charts, area.stacking.active controls stacked rendering and area.stacking.interpolation resolves missing values with 'linear', 'step', or 'none'.

`scale.includeZero` boolean

Include zero in the computed domain before padding and fixed bounds are applied.

`scale.padding` number

Fractional padding applied above and below auto domains.

`scale.min` number

Fixed minimum y value. Overrides the computed minimum.

`scale.max` number

Fixed maximum y value. Overrides the computed maximum.

`scale.tickMode` 'round' | 'exact'

'round' expands auto bounds to readable tick intervals. 'exact' divides the resolved range evenly.

`scale.tickTarget` number

Preferred number of y-axis ticks. Rounded ticks may vary slightly to keep labels readable.

`area` { up?: AreaValue, down?: AreaValue }

Main-view chart area override. Ignored when lane is set.

`style` ChartStyle

Sparse chart-level style overrides merged over options.chart.defaultStyle. See Chart Style.

Chart data is visual-only: it does not participate in article stacking, article selection, article drag handling, or getStatusForSave().

Chart Options new

Control visibility, geometry, grid-line defaults, default data, default styling, and initial data for timeline-aligned line and area charts.

These options live under options.chart.*. The values shown below are the defaults.

JavaScript

// Chart options (defaults)
{
  visible: true,
  area: { up: 'edge', down: 0 },
  gridLine: { /* global grid-line defaults */ },
  defaultData: {},
  defaultStyle: { /* see Chart Style */ },
  data: [ /* see Chart Schema */ ]
};

`visible` boolean

Draw loaded charts when true. Toggle this to hide every chart without unloading timeline.charts.

`area` object

Main-view chart area relative to the shared main line. Each side accepts pixel counts, 'edge', or { value: 'edge', padding: <px> }. Lane-scoped charts ignore this and use the lane body.

`defaultStyle` ChartStyle

Base styles merged into every chart before chart-level and series-level overrides. See Chart Style.

`gridLine` ChartGridLineOptions

Global x/y grid-line defaults merged into each chart style. Use this for consistent vertical and horizontal grid lines across charts.

`defaultData` Partial<ChartData>

Default chart data merged into every loaded chart before the chart's own data. The chart id is never inherited from defaults.

`data` ChartData[]

Initial charts loaded during timeline construction. Each entry follows the Chart Schema.

Chart Style new

Customize chart padding, x/y grid lines, axes, legends, default line styling, area fills, and point markers. Per-chart and per-series overrides merge deeply with this default object.

chart.defaultStyle in the Chart Options object.

JavaScript

// Chart defaultStyle
{
  padding: {
    top: 8,
    right: 12,
    bottom: 8,
    left: 48
  },
  backgroundColor: 'rgba(255, 255, 255, 0)',
  gridLine: {
    x: {
      major: { visible: true, color: 'rgba(0, 0, 0, 0.08)', thickness: 1 },
      minor: { visible: true, color: 'rgba(0, 0, 0, 0.035)', thickness: 2, minimumSpacing: 20 }
    },
    y: {
      major: { visible: true, color: 'rgba(120, 120, 120, 0.24)', thickness: 1 }
    }
  },
  axis: {
    visible: true,
    color: 'rgba(80, 80, 80, 0.45)',
    lineWidth: 1
  },
  yAxis: {
    visible: true,
    font: 'normal 11px Calibri',
    color: '#555',
    margin: 6,
    thousandsSeparator: ',',
    formatter: null
  },
  legend: {
    visible: 'auto',
    position: 'top-left',
    font: 'normal 12px Calibri',
    color: '#333',
    markerSize: 10,
    markerGap: 4,
    itemGap: 12,
    inset: { x: 8, y: 8 }
  },
  series: {
    color: '#2563eb',
    lineWidth: 2,
    lineDash: [],
    area: {
      fillColor: null,
      opacity: 0.2
    },
    point: {
      visible: false,
      radius: 2.5,
      fillColor: null,
      strokeColor: null,
      lineWidth: 1
    }
  }
};

`padding` object

Insets between the chart geometry and the plot rectangle. Increase left when y-axis labels need more space.

`padding.top` number

Space above the plot area in pixels.

`padding.right` number

Space to the right of the plot area in pixels.

`padding.bottom` number

Space below the plot area in pixels.

`padding.left` number

Space for y-axis labels and the plot's left edge.

`backgroundColor` string

Fill color for the chart geometry before grid and series drawing. Use RGBA for translucent overlays.

`gridLine` object

Chart-local x/y grid line styling. X grid lines reuse timeline marker positions and y grid lines use chart tick positions.

`gridLine...visible` boolean

Draw that grid-line group when true. Supported groups are x.major, x.minor, and y.major.

`gridLine...color` string

Grid line stroke color.

`gridLine...thickness` number

Grid line thickness in canvas pixels. Minor x grid lines also support minimumSpacing.

`axis` object

Left and bottom axis line styling.

`axis.visible` boolean

Draw chart axes when true.

`axis.color` string

Axis stroke color.

`axis.lineWidth` number

Axis line width in canvas pixels.

`yAxis` object

Numeric y-axis label settings.

`yAxis.visible` boolean

Draw numeric y-axis labels when true.

`yAxis.font` string

Canvas font declaration for labels.

`yAxis.color` string

Label text color.

`yAxis.margin` number

Gap between labels and the plot's left edge.

`yAxis.thousandsSeparator` string | null

Separator used to group thousands in the default numeric labels. Set it to null or an empty string to disable grouping. A custom formatter takes precedence.

`yAxis.formatter` function | null

Optional function receiving a tick value and returning the label text. Defaults to compact numeric labels using the configured thousandsSeparator.

`legend` object

Legend settings. Only titled series are included.

`legend.visible` boolean | 'auto'

'auto' draws a legend only when at least two series have titles.

`legend.position` 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'

Plot-area corner used as the legend anchor.

`legend.font` string

Canvas font declaration for legend labels.

`legend.color` string

Legend text color.

`legend.markerSize` number

Width and height for each legend marker.

`legend.markerGap` number

Gap between each color marker and its label text.

`legend.itemGap` number

Horizontal gap between separate legend entries.

`legend.inset` { x: number, y: number }

Distance inward from the selected plot-area corner.

`series` object

Base line and point marker styling merged into every series. Individual series can override these fields.

`series.color` string

Stroke color for lines and default fill color for point markers. Untouched series can also use the built-in palette.

`series.lineWidth` number

Line width in canvas pixels.

`series.lineDash` number[]

Dash pattern passed to ctx.setLineDash(...) when supported.

`series.area` object

Area fill styling for type: 'area' charts.

`series.area.fillColor` string | null

Area fill color. null falls back to the series color.

`series.area.opacity` number

Area fill opacity clamped between 0 and 1.

`series.point` object

Point marker settings for finite chart values.

`series.point.visible` boolean

Draw circular point markers when true.

`series.point.radius` number

Point marker radius in pixels.

`series.point.fillColor` string | null

Marker fill color. null falls back to the series color.

`series.point.strokeColor` string | null

Marker stroke color. null falls back to white.

`series.point.lineWidth` number

Marker stroke width. Set to 0 to skip marker strokes.

Per-chart and per-series overrides: call chart.setStyle, set ChartData.style, or set ChartSeriesData.style with a sparse object. Fields you omit fall back to the defaults above.

Chart Methods new

Load, remove, inspect, and update charts after your timeline is initialized.

Tip: Loaded charts are stored as Chart instances in timeline.charts. Retrieve one with timeline.getChartById(id) before calling the instance methods below.

timeline.loadCharts(charts)

Data

Add one or more new charts and redraw the timeline.

Parameters

charts ChartData[]

Array of Chart objects. Each entry follows the Chart Schema.

Returns

void – Adds new charts and redraws.

Charts without ids, charts whose ids are already loaded, and repeated ids in the same batch are skipped with a warning. Charts omitted from later calls remain loaded until removed or cleared.

timeline.loadCharts([
  {
    id: 'population',
    scale: { includeZero: true },
    series: [
      {
        id: 'world',
        title: 'World',
        points: [
          { date: { year: 1990 }, value: 5.3 },
          { date: { year: 2000 }, value: 6.1 },
          { date: { year: 2010 }, value: 6.9 },
          { date: { year: 2020 }, value: 7.8 }
        ]
      }
    ]
  }
]);

timeline.loadLaneCharts(laneId, charts)

Data

Stamp a lane id onto a batch of charts and load them onto the timeline.

Parameters

laneId string | number

Lane identifier to assign to every chart in the batch.

charts ChartData[]

Chart objects. Existing conflicting lane values are overwritten by laneId.

Returns

void – Adds new lane-scoped charts and redraws.

timeline.loadLaneCharts('metrics', [
  {
    id: 'temperature',
    series: [
      {
        id: 'average',
        points: [
          { date: { year: 1900 }, value: 13.7 },
          { date: { year: 1950 }, value: 13.9 },
          { date: { year: 2000 }, value: 14.4 }
        ]
      }
    ]
  }
]);

chart.addSeries(series)

Data

Add one series to a loaded chart, re-resolve chart data, and redraw.

Parameters

series ChartSeriesData

Series object with optional id, title, points, and style.

Returns

void.

const chart = timeline.getChartById('population');

chart?.addSeries({
  id: 'projection',
  title: 'Projection',
  points: [
    { date: { year: 2030 }, value: 8.5 },
    { date: { year: 2040 }, value: 9.1 }
  ]
});

chart.removeSeriesById(id)

Data

Remove one series by id, re-resolve the chart, and redraw when found.

Parameters

id string | number

Series id to remove.

Returns

boolean – true when a series was removed; otherwise false.

chart.removeSeriesById('projection');

chart.getSeriesById(id)

Lookup

Return the normalized runtime series with the matching id.

Returns

ChartSeries | undefined.

const series = chart.getSeriesById('projection');
console.log(series?.points.length);

timeline.removeChart(id)

Data

Remove one loaded chart by id.

Parameters

id string | number

Chart id to remove.

Returns

boolean – true when a chart was removed; otherwise false.

const removed = timeline.removeChart('population');

timeline.clearCharts()

Data

Remove all loaded charts and redraw the timeline.

Returns

void.

timeline.clearCharts();

timeline.getChartById(id)

Lookup

Return a loaded Chart instance by id.

Parameters

id string | number

Chart id to retrieve.

Returns

Chart | undefined.

const chart = timeline.getChartById('population');
chart?.setStyle('series.lineWidth', 3);

chart.setOption(option, value?)

Configuration

Update chart data fields using objects or dot-notation paths.

Parameters

option string | object

Partial chart object for batch updates, or a dot-notation path such as 'scale.includeZero'.

value any

New value when using a string path. Omit this argument to read the current value.

Returns

any when called as a getter; otherwise void.

const chart = timeline.getChartById('population');

chart.setOption('visibility', 'hidden');
chart.setOption({
  scale: { source: 'viewport', padding: 0.1 }
});

chart.setStyle(option, value?)

Styling

Override chart styles or query an override value.

Parameters

option string | object

Partial style object or dot-notation path such as 'gridLine.y.major.visible'.

value any

New value when using a string path. Omit to read the current override.

Returns

any when reading; otherwise void.

const chart = timeline.getChartById('population');

chart.setStyle('gridLine.y.major.visible', false);
chart.setStyle({
  gridLine: {
    x: {
      minor: { visible: true, minimumSpacing: 48 }
    }
  },
  series: {
    lineWidth: 3,
    point: { visible: true }
  }
});

chart.getScaleDomain(drawCycleContext?)

Inspection

Resolve the active y-domain for a chart.

Parameters

drawCycleContext RedrawCycleContext

Optional render context. Only needed for scale.source: 'viewport'.

Returns

{ min: number, max: number }.

timeline.on('timeline-render-end', ({ drawCycleContext }) => {
  const chart = timeline.getChartById('population');
  console.log(chart?.getScaleDomain(drawCycleContext));
});

Need More Help?

If you can't find what you're looking for, browse the examples or contact us.

Contact Support Browse Examples