# Target lines

> Draw goals, limits and averages across a chart with targetLine(), on a preset or in a composed chart, horizontal or vertical.

A number on its own says little. Is 950 good? Against a goal of 1000, you see it at a glance. `targetLine()` draws that line: a goal, a limit or an average, across the chart at a value, with a label if you want one. It works on the presets and in composed charts, and you style it with CSS like the rest of the chart. For the trend of a series, see [trend lines](https://chartist.dev/packages/essentials/trend-lines/).

It comes from `@chartist-js/essentials`, with its stylesheet after Chartist's:

```ts
import 'chartist/styles.css';
import '@chartist-js/essentials/styles.css';
```

## A target line

Presets take extra layers in their `layers` option: `above` draws them on top of the bars or lines, `below` behind them.

**A goal line** (runs in the browser):

`src/main.ts`:

```ts
import 'chartist/styles.css';
import '@chartist-js/essentials/styles.css';
import { barChart } from 'chartist';
import { targetLine } from '@chartist-js/essentials';

barChart(
  '#chart',
  {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
    series: [[820, 950, 1100, 760, 1240, 980]]
  },
  {
    low: 0,
    // Extra layers on top of the bars.
    layers: { above: [targetLine({ value: 1000, label: 'Goal' })] }
  }
);
```

`index.html`:

```html
<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <script type="module" src="/src/main.ts"></script>
  </head>
  <body>
    <div id="chart" class="ct-golden-section"></div>
  </body>
</html>
```

[Responsive options](https://chartist.dev/docs/responsive/) can change the layers too: a `layers: { above: [...] }` entry replaces the `above` list and keeps `below`.

The Y axis makes room for the line: a goal above all the bars still shows. A `low` or `high` you set on the axis wins, and a line outside it isn't drawn.

| Option          | What it does                                                              |
| --------------- | ------------------------------------------------------------------------- |
| `value`         | Where the line goes, on the axis                                          |
| `label`         | Text next to the line (optional)                                          |
| `className`     | Extra class for the line and its label, such as `ct-series-b` for a color |
| `axis`          | The id of the axis the value is on; by default the first Y axis           |
| `labelPosition` | `'end'` (default) or `'start'` of the line                                |

## Several lines

One layer draws one line. For a minimum and a goal, add two, and give one a series color with `className`:

**A goal and a minimum** (runs in the browser):

`src/main.ts`:

```ts
import 'chartist/styles.css';
import '@chartist-js/essentials/styles.css';
import { barChart } from 'chartist';
import { targetLine } from '@chartist-js/essentials';

// Monthly sales against a goal and a minimum, on the bar chart preset.
barChart(
  '#chart',
  {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
    series: [[820, 950, 1100, 760, 1240, 780]]
  },
  {
    low: 0,
    // One layer per line.
    layers: {
      above: [
        targetLine({ value: 1000, label: 'Goal' }),
        targetLine({ value: 800, label: 'Minimum', className: 'ct-series-b' })
      ]
    }
  }
);
```

`index.html`:

```html
<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <script type="module" src="/src/main.ts"></script>
  </head>
  <body>
    <div id="chart" style="height: 50vh"></div>
  </body>
</html>
```

## Vertical lines

On an X axis, the lines are vertical. That's where the values are on horizontal bars: the presets call their axes `x` and `y`, so use `targetLine({ axis: 'x', value })`. In a [composed chart](https://chartist.dev/docs/composed-charts/), use your own axis ids. Here the line is the average, computed from the data:

**An average on horizontal bars** (runs in the browser):

`src/main.ts`:

```ts
import 'chartist/styles.css';
import '@chartist-js/essentials/styles.css';
import { barChart } from 'chartist';
import { targetLine } from '@chartist-js/essentials';

const minutes = [34, 52, 41, 27, 48];
const average = minutes.reduce((sum, value) => sum + value, 0) / minutes.length;

// Minutes per visit on horizontal bars: the values are on the X axis, so
// the average is a vertical line there.
barChart(
  '#chart',
  {
    labels: ['Home', 'Docs', 'Examples', 'Plugins', 'Playground'],
    series: [minutes]
  },
  {
    horizontalBars: true,
    reverseData: true,
    axisY: { offset: 80 },
    low: 0,
    layers: {
      above: [targetLine({ axis: 'x', value: average, label: 'Average' })]
    }
  }
);
```

`index.html`:

```html
<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <script type="module" src="/src/main.ts"></script>
  </head>
  <body>
    <div id="chart" class="ct-golden-section"></div>
  </body>
</html>
```

A target line next to a range: put a [band](https://chartist.dev/docs/bands/) behind it.

## Styling

A target line draws in the text color by default, dashed, so it reads as context behind the data. Change it with custom properties, or give it a series color with `className: 'ct-series-c'`:

```css
.ct-chart {
  --ct-target-line-color: #c8102e;
  --ct-target-line-width: 3px;
  --ct-target-line-dasharray: none;
}
```

The markup: a `line.ct-target-line` and a `text.ct-target-label` per line. In listeners and plugins, find them by the roles `targetLine` and `targetLabel`, as in [events and plugins](https://chartist.dev/docs/events-and-plugins/). Importing `@chartist-js/essentials` declares the roles, so TypeScript knows their contexts.

> **Coming from the target line plugin?** `chartist-plugin-targetline` with
> `{ value: 1000 }` becomes `layers: { above: [targetLine({ value: 1000 })] }`.
> The line keeps the class `ct-target-line`, so your CSS still applies. You
> also get labels, any axis, and server rendering.