#Line Chart

Plot one series of points as a line, with a dot at each point, and a touch tooltip, pan and zoom, and dark mode built in.

#Installation

npx @blotch/dolan add line-chart

import { UiLineChart } from '../components/ui/line-chart';

This also adds Chart, which draws the preset, and installs the npm packages @tanstack/charts and d3-shape.

#Usage

import { Component } from '@angular/core';
import { UiLineChart } from '../components/ui/line-chart';

@Component({
  selector: 'app-revenue',
  imports: [UiLineChart],
  template: `<ui-line-chart [data]="revenue" label="Monthly revenue" />`,
})
export class Revenue {
  protected readonly revenue = [
    { x: 1, y: 12 },
    { x: 2, y: 19 },
    { x: 3, y: 15 },
    { x: 4, y: 25 },
  ];
}

• data is an array of { x, y } points, both numbers. The axes fit rounded ranges to the data.
• Touch the chart to see a point's values in a tooltip. Tap to pin it.
• Set label so a screen reader can say what the chart shows.

#Customize

#Colors

color sets the line and the dots. A theme color such as var(--chart-2) switches with dark mode. A fixed color such as rgba(59, 130, 246, 1) stays the same.

<ui-line-chart [data]="downloads" color="var(--chart-2)" />

#Shape

smooth draws a curve through the points instead of straight segments. The curve is monotone (d3's curveMonotoneX), so it never overshoots the data.

<ui-line-chart
  [data]="revenue"
  [smooth]="true"
  [strokeWidth]="3"
  [dotRadius]="4"
/>

strokeWidth and dotRadius are in px. Set showDots to false for a line without dots.

#Axes and range

xAxisLabel and yAxisLabel add axis titles. Horizontal gridlines are on by default: showGrid turns them off, and showXGrid adds vertical ones.

<ui-line-chart
  [data]="revenue"
  xAxisLabel="Month"
  yAxisLabel="Revenue ($k)"
  [yMin]="0"
/>

• xMin, xMax, yMin and yMax fix a bound instead of fitting the data. [yMin]="0" starts the axis at zero.
• xTickFormat and yTickFormat turn tick values into labels, such as (value) => months[value - 1].
• tickCount sets roughly how many ticks each axis gets. The axis picks round values near it.

#Padding

padding insets the plot, each side as a fraction (0 to 1) of its size. Use it to keep the first and last dots off the frame.

<ui-line-chart [data]="revenue" [padding]="{ left: 0.05, right: 0.05 }" />

#Size

The chart fills its container's width and is 200px tall. Set height for another height and width for a fixed width, both in px. Use height rather than a height class, because the preset always sets a height.

<ui-line-chart [data]="revenue" [height]="160" />

#Interaction

#Taps

pointTap emits the tapped { x, y } point. A tap on empty space emits nothing. Set tooltip to false to turn the tooltip off.

<ui-line-chart [data]="revenue" (pointTap)="selected.set($event)" />

pointTap fires inside the touch, so wrap router navigation in setTimeout (see the setTimeout rule).

#Pan and zoom

Set zoomable to let users drag to pan, with +, − and 1:1 buttons. zoomAxes limits it to one axis.

<ui-line-chart [data]="revenue" [zoomable]="true" zoomAxes="x" />

To zoom from your own controls, set showZoomControls to false and call zoomIn(), zoomOut() or resetZoom() on the component. See Pan and zoom for how it behaves.

#API

#UiLineChart

XYDatum is { x: number; y: number }. ChartPadding is { top?, right?, bottom?, left? }, each a fraction (0–1) of the plot's size, with omitted sides 0. Both are exported from ../components/ui/chart.

#lineChartDefinition

function lineChartDefinition(options: LineChartOptions): ChartDefinition;

Returns the TanStack Charts definition <ui-line-chart> renders. The options are the inputs that shape the chart, with the same defaults: data, color, strokeWidth, dotRadius, showDots, smooth, tickCount, showGrid, showXGrid, xAxisLabel, yAxisLabel, padding, xMin, xMax, yMin, yMax, xTickFormat, yTickFormat and tooltip. Size, label, color scheme and zoom are inputs of <ui-chart> instead.

Start from it to add marks of your own, such as a target line, and render the result with <ui-chart>:

import { defineChart, ruleY } from '@tanstack/charts/universal';
import { lineChartDefinition } from '../components/ui/line-chart';

const base = lineChartDefinition({ data: revenue, smooth: true, yMin: 0 });

protected readonly withTarget = defineChart({
  ...base,
  marks: [...base.marks, ruleY([20], { stroke: 'var(--muted-foreground)' })],
});

#Related

• Chart: several series, overlays and other marks
• Area Chart: a line with the area below it filled
• Scatter Chart: points without a line