# @chartist-js/essentials API > Every function and type @chartist-js/essentials exports. Types from `chartist` link to the Chartist API reference. ## axisTitle ```ts function axisTitle(options: AxisTitleOptions): Layer ``` Names an axis with a title next to its labels, on any side of the chart. The layer reserves the room the title needs, so the drawing area shrinks and the title never overlaps the labels, whatever font size the stylesheet gives it. One layer draws one title; give each axis its own. Titles on the same side stack outward in the order of `layers`. The title is an SVG `text` with the classes `ct-axis-title`, `ct-horizontal` or `ct-vertical` and `ct-start` or `ct-end`, styled with `--ct-axis-title-color` and `--ct-axis-title-size` from `@chartist-js/essentials/styles.css`. Parameters: - `options: AxisTitleOptions` ```ts import { lineChart } from 'chartist'; import { axisTitle } from '@chartist-js/essentials'; import 'chartist/styles.css'; import '@chartist-js/essentials/styles.css'; lineChart( '#chart', { labels: ['Mon', 'Tue', 'Wed'], series: [[12, 9, 7]] }, { layers: { above: [ axisTitle({ axis: 'x', text: 'Day' }), axisTitle({ axis: 'y', text: 'Visits' }) ] } } ); ``` ## logAxis ```ts function logAxis(options?: LogAxisOptions): AxisFactory ``` Creates a logarithmic axis, for values that span several orders of magnitude: each power of the base (1, 10, 100, … for base 10) is the same distance from the next, so growth by a factor looks the same everywhere. It goes in the `type` of a preset's `axisX` or `axisY`, or of an axis of `cartesianAxes()`. Without `low` and `high`, the range runs from the power at or below the smallest value to the power at or above the largest; the axis's own `low` and `high` set it exactly. The ticks are the powers, every second or third when they'd be closer than `scaleMinSpace`; the axis's `ticks` replace them. Zero and negative values have no place on a log scale: they don't count towards the range and are drawn at the start of the axis, so a bar for zero has no length. Use `null` for a gap. Trend lines on a log axis are fitted to the logarithms of the values, so they're straight on the axis: an exponential trend on a log Y axis. Parameters: - `options?: LogAxisOptions` The base and whether to draw minor grid lines. ```ts import { lineChart } from 'chartist'; import { logAxis } from '@chartist-js/essentials'; lineChart( '#chart', { labels: ['2019', '2020', '2021', '2022', '2023', '2024'], series: [[120, 980, 4100, 36000, 210000, 850000]] }, { axisY: { type: logAxis({ minorTicks: true }), labelTransform: value => value.toLocaleString('en-US') } } ); ``` ## targetLine ```ts function targetLine(options: TargetLineOptions): Layer ``` Creates a layer that draws a line across the chart area at a constant value on one axis, such as a goal or a limit (`line.ct-target-line`). On a Y axis the line is horizontal, on an X axis vertical. It can have a label, drawn as SVG text (`text.ct-target-label`) next to it inside the chart area, and a class, e.g. `ct-series-b` for a series' color. The axis widens to include the value, unless its own `low` or `high` leave it out; a line outside the axis isn't drawn. For several lines, add a layer per line. Parameters: - `options: TargetLineOptions` ```ts import { lineChart } from 'chartist'; import { targetLine } from '@chartist-js/essentials'; import 'chartist/styles.css'; import '@chartist-js/essentials/styles.css'; lineChart( '#chart', { labels: ['Jan', 'Feb', 'Mar', 'Apr'], series: [[620, 810, 740, 930]] }, { low: 0, layers: { above: [ targetLine({ value: 700, label: 'Min' }), targetLine({ value: 1000, label: 'Goal', className: 'ct-series-b' }) ] } } ); ``` ## trendLine ```ts function trendLine(options?: TrendLineOptions): Layer ``` Creates a layer that draws a trend line for each series: the straight line that fits its values best (least squares), from its smallest to its largest X, as a `line.ct-trend-line` in a series group (`g.ct-series.ct-series-a`), so it takes the series' color. On a step axis X is the value's index, on a scale axis the value's `x`. Holes are skipped, and a series with fewer than two values gets no line. The Y axis widens to include the line's ends. On an axis with a transform, such as a log axis, the line is fitted to the transformed values, so it's straight on that axis: an exponential trend on a log Y axis. Add it next to the `line()` or `bar()` layer that draws the values. Parameters: - `options?: TrendLineOptions` ```ts import { lineChart } from 'chartist'; import { trendLine } from '@chartist-js/essentials'; import 'chartist/styles.css'; import '@chartist-js/essentials/styles.css'; lineChart( '#chart', { labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'], series: [{ name: 'sales', data: [620, 810, 740, 930, 880, 1020] }] }, { layers: { above: [trendLine()] } } ); ``` ## valueLabels ```ts function valueLabels(options?: ValueLabelsOptions): Layer ``` Creates a layer that writes each value next to the point or bar that shows it: above points, past the ends of bars, and in the middle of stacked segments. It draws from where the chart's other layers drew, after stacking, offsets and `compose` listeners, so add it as an extra layer: `layers.above` on a preset, anywhere in a composed chart. The text is the value along the value axis, written with `Intl.NumberFormat`; `format` gets the same item as the `format` of `@chartist-js/tooltips`. Labels that don't fit their bar, or would leave the chart, move to a place where they fit. They're SVG `text`, so they render on servers and in the terminal, styled with `--ct-value-label-color`, `--ct-value-label-inside-color` and `--ct-value-label-size` from `@chartist-js/essentials/styles.css`. Parameters: - `options?: ValueLabelsOptions` ```ts import { barChart } from 'chartist'; import { valueLabels } from '@chartist-js/essentials'; import 'chartist/styles.css'; import '@chartist-js/essentials/styles.css'; barChart( '#chart', { labels: ['Q1', 'Q2', 'Q3'], series: [[1250, 1830, 1470]] }, { layers: { above: [ valueLabels({ format: item => `${item.value} units` }) ] } } ); ``` ## AxisTitleOptions ```ts interface AxisTitleOptions ``` Options of [`axisTitle`](https://chartist.dev/packages/essentials/api/#axisTitle). Properties: - `axis: string` The id of the axis the title names: `x` or `y` on the presets, the ids you gave in `cartesianAxes()` in composed charts. - `text: string` The title's text; an empty text draws nothing and takes no room. - `align?: 'start' | 'middle' | 'end'` Where along the axis the title sits: at the start (left on X axes, the bottom on Y axes), in the middle or at the end. - `flip?: boolean` Turns titles of left and right axes to read from top to bottom instead of from bottom to top. Titles of top and bottom axes don't change. - `gap?: number` Space between the title and the axis labels, in px. - `className?: string` Extra class names for the title, e.g. `ct-series-b` for a color. - `classNames?: { … }` Replaces the default class: `title` instead of `ct-axis-title`. ## LogAxisOptions ```ts interface LogAxisOptions ``` Options of [`logAxis`](https://chartist.dev/packages/essentials/api/#logAxis). Properties: - `base?: number` The base of the logarithm: the ticks are its powers. Any finite number above 1, such as 2 for a scale that doubles; default 10. - `minorTicks?: boolean` Draws minor grid lines between the ticks, without labels: at 2 to 9 times each power for base 10, or at the powers left out when the ticks skip some. Style them with `--ct-grid-minor-*`. ## TargetLineContext ```ts interface TargetLineContext extends NoSeries ``` The context of a `targetLine` node: the line of a `targetLine()` layer, across the chart area at a value on an axis. Its ends are in px in the SVG. Properties: - `axis: ScaleAxis` The axis the value is on; `axis.dimension` is `x` or `y`. - `value: number` The value the line is drawn at. - `label?: string` The line's label, if it has one. - `x1: number` The X of the line's start, in px. - `y1: number` The Y of the line's start, in px. - `x2: number` The X of the line's end, in px. - `y2: number` The Y of the line's end, in px. - `seriesIndex?: undefined` Always absent: the node belongs to no series. - `valueIndex?: undefined` Always absent: the node stands for no value. ## TargetLabelContext ```ts interface TargetLabelContext extends NoSeries ``` The context of a `targetLabel` node: the label of a target line, and where it's anchored, in px in the SVG. Properties: - `axis: ScaleAxis` The axis of the line's value. - `value: number` The value of the line. - `text: string` The label as drawn. - `x: number` Px from the left edge of the SVG. - `y: number` Px from the top edge of the SVG. - `seriesIndex?: undefined` Always absent: the node belongs to no series. - `valueIndex?: undefined` Always absent: the node stands for no value. ## TrendLineContext ```ts interface TrendLineContext ``` The context of a `trendLine` node: the line a `trendLine()` layer fits through a series' values, `y = slope * x + intercept` in the axes' values (X is the value's index on a step axis). Its ends are in px in the SVG. Properties: - `seriesIndex: number` The series' index in the chart's data, across layers. - `valueIndex?: undefined` Always absent: the line stands for the whole series. - `slope: number` How much the fitted value changes per unit of X. On axes with a transform, such as a log axis, it's in their transformed values: on a base 10 log Y axis, the powers of ten per unit of X. - `intercept: number` The fitted value at X 0, in transformed values like `slope`. - `correlation?: number` How closely the values follow the line: Pearson's correlation coefficient r, from -1 (every value on a falling line) through 0 (no straight trend) to 1 (every value on a rising line). Its square is R², the share of the values' variation the line explains, as spreadsheets show it next to a trendline. It describes the fit, not how reliable it is: with two values it's always 1 or -1. On axes with a transform, it's computed in their transformed values, so it says how straight the values look on the chart. Absent when all values are equal, where it isn't defined. - `x1: number` The X of the line's start (the series' smallest X), in px. - `y1: number` The Y of the line's start, in px. - `x2: number` The X of the line's end (the series' largest X), in px. - `y2: number` The Y of the line's end, in px. ## TargetLineOptions ```ts interface TargetLineOptions ``` The options of the [`targetLine`](https://chartist.dev/packages/essentials/api/#targetLine) layer: the line's value, its label and class, and the axis it's on. For several lines, add a layer per line. Properties: - `value: number` The value the line is drawn at, on the layer's axis. On a step axis, the position by index, as for the axis's ticks. - `label?: string` The text drawn next to the line; no label without it. - `className?: string` Extra classes for the line and its label, e.g. `ct-series-b`. - `axis?: string` The id of the axis the value is on: a Y axis draws a horizontal line, an X axis a vertical one. Default: the first Y axis. - `labelPosition?: 'start' | 'end'` Where the label sits along the line: at the `end` (right, or top for a vertical line) or the `start` (left, or bottom). - `classNames?: { … }` Replaces the classes of what the layer draws: `line` (`ct-target-line`) and `label` (`ct-target-label`). ## TrendLineOptions ```ts interface TrendLineOptions ``` The options of the [`trendLine`](https://chartist.dev/packages/essentials/api/#trendLine) layer. Without them, it draws a trend line for every series, on the first X and Y axis. Properties: - `series?: readonly (string | number)[]` Series to draw a trend line for, by index or name; default: all series. - `x?: string` The id of the X axis to draw on; default: the first X axis. - `y?: string` The id of the Y axis to draw on; default: the first Y axis. - `align?: 'start' | 'center'` Where the line's ends sit on a step axis: at the `start` of their steps, as the points of `line()`, or at the `center`, where bars are centered. - `classNames?: { … }` Replaces the classes of what the layer draws: `series` (`ct-series`) and `line` (`ct-trend-line`). ## ValueLabelRole ```ts type ValueLabelRole = 'point' | 'bar' ``` The roles whose nodes get labels. ## PointLabelPosition ```ts type PointLabelPosition = 'above' | 'below' | 'left' | 'right' | 'center' ``` Where a point's label sits. ## BarLabelPosition ```ts type BarLabelPosition = 'end' | 'inside-end' | 'center' | 'inside-base' ``` Where a bar's label sits, from the bar's base to its value: past its end, inside its end, in its middle or inside its base. ## ValueLabelItem ```ts type ValueLabelItem = { [K in R]: { readonly role: K; readonly seriesIndex: number; readonly valueIndex: number; readonly value: number | { readonly x: number; readonly y: number }; readonly meta: unknown; readonly series: unknown; readonly seriesName?: string; readonly label?: string; readonly context: NodeRoles[K]['ctx'] } }[R] ``` The value a label is about: what `format` gets. It has the fields of the item `@chartist-js/tooltips` gives its `format`, under the same names, so a function written for one mostly works for the other. Checking `item.role` narrows `item.context` to that role's context. ## ValueLabelContext ```ts interface ValueLabelContext ``` The context of a `valueLabel` node. Properties: - `role: ValueLabelRole` The role of the node the label is for. - `seriesIndex: number` The series' index in the chart's data. - `valueIndex: number` The value's index in its series. - `value: unknown` The labeled value, as the node has it. - `meta: unknown` The value's `meta`. - `series: unknown` The series as given in the data. - `text: string` The label's text. - `position: 'left' | 'right' | 'end' | 'center' | 'above' | 'below' | 'inside-end' | 'inside-base'` Where the label ended up, after fitting. - `x: number` Px from the left edge of the SVG: where the text is anchored. - `y: number` Px from the top edge of the SVG: the first line's baseline. ## ValueLabelsOptions ```ts interface ValueLabelsOptions ``` Options of [`valueLabels`](https://chartist.dev/packages/essentials/api/#valueLabels). Properties: - `roles?: readonly R[]` The nodes that get labels: `point`, `bar` or both (the default). - `series?: readonly (string | number)[]` The series to label, by index or name; default: all of them. - `pointPosition?: PointLabelPosition` Where point labels sit; default `above`. - `barPosition?: BarLabelPosition` Where bar labels sit; default `end`, and `center` for segments of stacked bars. - `offset?: number` The gap in px between a point's center, or a bar's end or base, and the label's nearest edge; default 8 for points and 4 for bars. - `format?: (item: ValueLabelItem) => string | number | null | undefined` The label's text for a value: a string or a number. `undefined` keeps the default text, `null` or `''` draw no label, and `\n` starts a new line. - `numberFormat?: NumberFormatOptions` `Intl.NumberFormat` options for the default text. - `locale?: string | readonly string[]` The locale of the default text; default: the runtime's. Set it when charts render on a server, so the text doesn't depend on its locale. - `overflow?: 'fit' | 'show'` `fit` (the default) moves labels that don't fit their bar or would leave the chart; `show` draws every label where its position puts it. - `labels?: 'svg' | 'html'` SVG `text` (the default) or HTML in a `foreignObject`. - `classNames?: { … }` Replace the classes: `group` (`ct-value-labels`), `label` (`ct-value-label`) and `inside` (`ct-value-label-inside`).