# @chartist-js/essentials

> The additions people ask for most, as layers you add to a chart, kept out of the core so charts without them stay small.

Some things almost every chart grows sooner or later: a title for an axis, a value next to a bar, a legend. In 1.x they came from community plugins, each with its own way to load and its own guess at the padding. `@chartist-js/essentials` makes them layers like `line()` and `targetLine()`, made and released together with Chartist.

They're a package of their own so the core stays small: a chart pays only for the layers it imports. Today the package holds axis titles, which take the room they need and never land on your labels, [target](https://chartist.dev/packages/essentials/target-lines/) and [trend lines](https://chartist.dev/packages/essentials/trend-lines/), [value labels](https://chartist.dev/packages/essentials/value-labels/), and a [log axis](https://chartist.dev/packages/essentials/log-axis/) for values that span several orders of magnitude:

**Axis titles** (runs in the browser):

`src/main.ts`:

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

// Visits per day, with both axes named. Each title reserves its own room.
lineChart(
  '#chart',
  {
    labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
    series: [[1200, 1450, 1380, 1620, 1500, 980, 860]]
  },
  {
    low: 0,
    layers: {
      above: [
        axisTitle({ axis: 'x', text: 'Day of the week' }),
        axisTitle({ axis: 'y', text: 'Visits' })
      ]
    }
  }
);
```

`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>
```

## Install

```sh
npm install @chartist-js/essentials
```

It brings `chartist` along. Load its stylesheet after Chartist's:

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

### Without a bundler

From a CDN, map both packages in an import map. The package imports `chartist` by name, so the map gives it the same copy your page uses:

```html
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/chartist@2/dist/index.css"
/>
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@chartist-js/essentials@2/dist/styles.css"
/>
<script type="importmap">
  {
    "imports": {
      "chartist": "https://cdn.jsdelivr.net/npm/chartist@2/dist/index.min.js",
      "@chartist-js/essentials": "https://cdn.jsdelivr.net/npm/@chartist-js/essentials@2/dist/index.js"
    }
  }
</script>
<script type="module">
  import { lineChart } from 'chartist';
  import { axisTitle } from '@chartist-js/essentials';
</script>
```

## Quick start

The layers go where Chartist's own extra layers go: into `layers` on the presets, or into the list of a composed chart.

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

barChart(
  '#chart',
  { labels: ['Q1', 'Q2', 'Q3', 'Q4'], series: [[5, 4, 3, 7]] },
  {
    layers: {
      above: [
        axisTitle({ axis: 'x', text: 'Quarter' }),
        axisTitle({ axis: 'y', text: 'Orders (thousands)' })
      ]
    }
  }
);
```

They're part of the chart's scene, so they render on the server, hydrate and show in the terminal like everything else Chartist draws.

## Next

- [Axis titles](https://chartist.dev/packages/essentials/axis-titles/): sides, alignment, several axes and styling.
- [Target lines](https://chartist.dev/packages/essentials/target-lines/): goals, limits and averages, across or up and down.
- [Trend lines](https://chartist.dev/packages/essentials/trend-lines/): the trend of a series and how well it fits.
- [Value labels](https://chartist.dev/packages/essentials/value-labels/): each value next to its point or bar.
- [Log axis](https://chartist.dev/packages/essentials/log-axis/): decades, minor grid lines, zero values and trend lines.
- [API](https://chartist.dev/packages/essentials/api/): every function and option of the package.
- [Custom layers](https://chartist.dev/docs/custom-layers/): how layers like these are made, including the room they reserve.