# @chartist-js/terminal

> Chartist charts in the terminal and as text art in HTML, from the ct-cli command or from your own CLI tool.

Chartist builds every chart as a scene first, and SVG is one way to draw it. `@chartist-js/terminal` draws the same scene with characters: lines, points and areas in braille dots, bars in block characters, slices filled with dots, and the grid in box-drawing lines, all in Chartist's series colors.

The layout is Chartist's own, so the labels, the scale and the options you know carry over. This is `lineChart()` with `showArea` and `lineSmooth`, 34 characters wide, as text art in the page, framed as a terminal window with a bit of CSS:

**Text art** (runs in the browser):

`src/main.ts`:

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

const data = {
  labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
  series: [
    [12, 9, 7, 8, 5],
    [2, 1, 3.5, 7, 3]
  ]
};

// The options of Chartist's lineChart(), plus a size in characters, as
// HTML instead of terminal escape codes.
const art = document.querySelector('#art');
if (art) {
  art.innerHTML = lineChart(data, {
    low: 0,
    showArea: true,
    lineSmooth: true,
    columns: 34,
    rows: 16,
    format: 'html'
  });
}
```

`src/style.css`:

```css
/* A terminal window around the text art, for the looks. It takes the
   chart's size: more columns or rows make it bigger. */
.window {
  width: fit-content;
  max-width: 100%;
  margin: 0 auto;
  border-radius: 10px;
  overflow: hidden;
  background: #17161c;
  box-shadow:
    0 1px 0 rgba(255, 255, 255, 0.06) inset,
    0 12px 32px rgba(0, 0, 0, 0.35);
}

.title-bar {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 10px 12px;
  background: #2a2830;
}

.dot {
  width: 12px;
  height: 12px;
  border-radius: 50%;
  background: #ff5f57;
}

.dot:nth-child(2) {
  background: #febc2e;
}

.dot:nth-child(3) {
  background: #28c840;
}

.title {
  flex: 1;
  margin-right: 52px;
  text-align: center;
  color: #a8a6b0;
  font:
    600 12px system-ui,
    sans-serif;
}

.screen {
  padding: 12px;
  color: #e6e4ec;
  /* Text art reads the same custom properties as SVG charts. */
  --ct-label-color: rgba(255, 255, 255, 0.7);
  --ct-grid-color: rgba(255, 255, 255, 0.16);
}

.screen .ct-terminal {
  margin: 0;
  font-size: 13px;
  /* Narrower than the chart, the window cuts it off. */
  overflow: hidden;
  /* Bold labels; the dots and lines come from the stylesheet's own font. */
  font-weight: 700;
}

/* On the dark screen, the area shading needs a little more. */
.screen .ct-area {
  opacity: 0.75;
}
```

`index.html`:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Text art</title>
  </head>
  <body>
    <div class="window">
      <div class="title-bar" aria-hidden="true">
        <span class="dot"></span>
        <span class="dot"></span>
        <span class="dot"></span>
        <span class="title">ct-cli</span>
      </div>
      <div class="screen">
        <div id="art"></div>
      </div>
    </div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>
```

## Install

```sh
npm install @chartist-js/terminal@next
```

It brings `chartist` along. The command needs Node.js 22 or later; the API runs in any JavaScript runtime, browsers included. To try the command without installing it:

```sh
npx @chartist-js/terminal@next demo
```

## Quick start

In a terminal, give `ct-cli` a chart type and a series per argument:

```sh
npx @chartist-js/terminal@next line 12,9,7,8,5 2,1,3.5,7,3 --labels Mon,Tue,Wed,Thu,Fri --area
```

In your own CLI tool, the chart functions take the data and options of Chartist's presets, plus a size in characters, and return the chart as a string:

```ts
import { barChart } from '@chartist-js/terminal';

console.log(
  barChart(
    {
      labels: ['Q1', 'Q2', 'Q3', 'Q4'],
      series: [
        [5, 4, 3, 7],
        [3, 2, 9, 5]
      ]
    },
    { stackBars: true, columns: 50, rows: 12 }
  )
);
```

## Next

- [Terminal rendering](https://chartist.dev/packages/terminal/terminal-rendering/): the command's input and options, the API for CLI tools, and text art in HTML.
- [Customizing charts](https://chartist.dev/packages/terminal/customizing-charts/): interpolation, axes, stacked bars and gauges, with Chartist's options.
- [Plugins](https://chartist.dev/packages/terminal/plugins/): what the terminal draws of the nodes a plugin adds.
- [API](https://chartist.dev/packages/terminal/api/): every function and option of the package.
- [Server rendering](https://chartist.dev/docs/server-rendering/): the same scene as SVG markup, without a browser.
- [Rendering](https://chartist.dev/api/rendering/) in the Chartist API: `toScene()`, the renderers and text measuring this package builds on.