# @chartist-js/terminal API

> Every function and type @chartist-js/terminal exports. Types from `chartist` link to the Chartist API reference.

## renderToTerminal

*experimental*

```ts
function renderToTerminal(scene: SceneNode, options?: TerminalRenderOptions): string
```

Renders a scene as text for a terminal: lines, points and areas in braille dots, bars in block characters, slices filled, the grid in dim box-drawing characters, labels as text, all colored by series with ANSI escape codes. Lay the scene out with [`terminalSize`](https://chartist.dev/packages/terminal/api/#terminalSize), so its px map to cells.

Parameters:

- `scene: SceneNode`
- `options?: TerminalRenderOptions`

```ts
import { lineChartConfig, toScene } from 'chartist';
import { renderToTerminal, terminalSize } from '@chartist-js/terminal';

const scene = toScene(
  lineChartConfig({ labels: ['Mon', 'Tue', 'Wed'], series: [[5, 2, 4]] }),
  terminalSize(60, 15)
);
console.log(renderToTerminal(scene, { color: '256' }));
```

## lineChart

*experimental*

```ts
function lineChart(data: LineChartData, options?: TerminalLineChartOptions): string
```

Renders a line chart for the terminal, from the data and options of Chartist's `lineChart`, at `columns` × `rows` cells: lines and areas in braille dots, colored by series.

Parameters:

- `data: LineChartData`
- `options?: TerminalLineChartOptions`

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

console.log(
  lineChart(
    { labels: ['Mon', 'Tue', 'Wed', 'Thu'], series: [[12, 9, 7, 8], [2, 1, 3.5, 7]] },
    { columns: 60, rows: 15, showArea: true, color: '256' }
  )
);
```

## barChart

*experimental*

```ts
function barChart(data: BarChartData, options?: TerminalBarChartOptions): string
```

Renders a bar chart for the terminal, from the data and options of Chartist's `barChart` (stacked, horizontal and the others), at `columns` × `rows` cells: bars in block characters, colored by series.

Parameters:

- `data: BarChartData`
- `options?: TerminalBarChartOptions`

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

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

## pieChart

*experimental*

```ts
function pieChart(data: PieChartData, options?: TerminalPieChartOptions): string
```

Renders a pie or donut chart for the terminal, from the data and options of Chartist's `pieChart`, at `columns` × `rows` cells: slices filled with braille dots, each label on its slice.

Parameters:

- `data: PieChartData`
- `options?: TerminalPieChartOptions`

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

console.log(
  pieChart(
    { labels: ['Bananas', 'Apples', 'Kiwis'], series: [20, 10, 30] },
    { donut: true, columns: 40, rows: 16 }
  )
);
```

## detectColorMode

*experimental*

```ts
function detectColorMode(stream: ColorStream, env: Readonly<Record<string, string | undefined>>): ColorMode
```

Picks the color mode for an output stream from environment variables, the way most CLI tools do:

- none when `NO_COLOR` is set, `TERM` is `dumb` or the stream isn't a   terminal;
- `FORCE_COLOR` overrides that: `0` none, `1` 16 colors, `2` 256 colors,   `3` 24-bit;
- otherwise 24-bit when `COLORTERM` is `truecolor` or `24bit`, else 256   colors.

It reads only what it's given, so it works outside Node.js too.

Parameters:

- `stream: ColorStream` The output, usually `process.stdout`
- `env: Readonly<Record<string, string | undefined>>` The environment variables, usually `process.env`

```ts
import { detectColorMode, lineChart } from '@chartist-js/terminal';

const color = detectColorMode(process.stdout, process.env);
console.log(lineChart({ series: [[1, 3, 2]] }, { color }));
```

## CELL_WIDTH

*experimental*

```ts
const CELL_WIDTH: 8
```

The width in px a terminal cell stands for in a scene: a glyph is half as wide as high.

## CELL_HEIGHT

*experimental*

```ts
const CELL_HEIGHT: 16
```

The height in px a terminal cell stands for in a scene: one line.

## measureCells

*experimental*

```ts
const measureCells: MeasureText
```

Measures text in terminal cells: each character is one cell wide and one cell high, so labels are laid out on the character grid.

## terminalSize

*experimental*

```ts
function terminalSize(columns: number, rows: number): SceneSize
```

The size to lay out a chart at for `columns` × `rows` terminal cells, for `toScene()`: in px, with text measured in cells and SVG text labels.

Parameters:

- `columns: number`
- `rows: number`

## renderToHtml

*experimental*

```ts
function renderToHtml(scene: SceneNode): string
```

Renders a scene as HTML text art: the terminal output in a `pre` element (class `ct-terminal`), each run of cells in a span with classes instead of colors: `ct-series-a` to `ct-series-z`, `ct-bg-series-a` for the series behind a cell, and the kind (`ct-grid`, `ct-label`, `ct-area`, `ct-bar`, `ct-line`, `ct-point`, `ct-slice`). Load `@chartist-js/terminal/styles.css` to color it; it reads Chartist's `--ct-series-a` and other custom properties, so themes apply, and draws braille, blocks and grid lines with a font of its own that fills each cell. Each character is an `i` element: one cell. Lay the scene out with [`terminalSize`](https://chartist.dev/packages/terminal/api/#terminalSize).

Parameters:

- `scene: SceneNode`

```ts
import { pieChartConfig, toScene } from 'chartist';
import { renderToHtml, terminalSize } from '@chartist-js/terminal';
import '@chartist-js/terminal/styles.css';

const scene = toScene(
  pieChartConfig({ labels: ['A', 'B'], series: [3, 2] }),
  terminalSize(30, 12)
);
document.querySelector('#chart')!.innerHTML = renderToHtml(scene);
```

## legend

*experimental*

```ts
function legend(data: { readonly labels?: readonly unknown[]; readonly series?: readonly unknown[] }, options?: LegendOptions): string
```

Makes a legend for a chart's data: a colored marker and the name of each named series (series objects with a `name`), in series colors. For pie data, whose series are values, the names are the labels. Series without a name are left out but keep their color. Returns an empty string when nothing has a name.

Parameters:

- `data: { readonly labels?: readonly unknown[]; readonly series?: readonly unknown[] }`
- `options?: LegendOptions`

```ts
import { legend, lineChart } from '@chartist-js/terminal';

const data = {
  labels: ['Mon', 'Tue', 'Wed'],
  series: [
    { name: 'Visitors', data: [12, 9, 7] },
    { name: 'Sign-ups', data: [2, 1, 3] }
  ]
};
console.log(lineChart(data, { columns: 60, rows: 12 }));
console.log(legend(data, { columns: 60 }));
```

## TerminalRenderOptions

```ts
interface TerminalRenderOptions
```

Options of [`renderToTerminal`](https://chartist.dev/packages/terminal/api/#renderToTerminal).

Properties:

- `color?: ColorMode` How colors are written; `none` writes plain text.
- `palette?: readonly string[]` Series colors as hex, by series letter (`a` first); Chartist's default series colors otherwise. Series past the end start over.

## TerminalChartOptions

```ts
interface TerminalChartOptions
```

The terminal options of the chart functions, next to the 1.x options.

Properties:

- `columns?: number` The width in terminal columns.
- `rows?: number` The height in terminal rows.
- `color?: ColorMode` How text output is colored; HTML output uses classes instead.
- `palette?: readonly string[]` Series colors as hex for text output, by series letter (`a` first).
- `format?: 'html' | 'text'` `text` for terminals, or `html` for [`renderToHtml`](https://chartist.dev/packages/terminal/api/#renderToHtml) markup.

## TerminalLineChartOptions

*experimental*

```ts
type TerminalLineChartOptions = Omit<LineChartPresetOptions, 'width' | 'height'> & TerminalChartOptions
```

Options of the terminal [`lineChart`](https://chartist.dev/packages/terminal/api/#lineChart): the options of Chartist's `lineChart` and the terminal options.

Properties:

- `columns?: number` The width in terminal columns.
- `rows?: number` The height in terminal rows.
- `color?: ColorMode` How text output is colored; HTML output uses classes instead.
- `palette?: readonly string[]` Series colors as hex for text output, by series letter (`a` first).
- `format?: 'html' | 'text'` `text` for terminals, or `html` for [`renderToHtml`](https://chartist.dev/packages/terminal/api/#renderToHtml) markup.

## TerminalBarChartOptions

*experimental*

```ts
type TerminalBarChartOptions = Omit<BarChartPresetOptions, 'width' | 'height'> & TerminalChartOptions
```

Options of the terminal [`barChart`](https://chartist.dev/packages/terminal/api/#barChart): the options of Chartist's `barChart` and the terminal options.

Properties:

- `columns?: number` The width in terminal columns.
- `rows?: number` The height in terminal rows.
- `color?: ColorMode` How text output is colored; HTML output uses classes instead.
- `palette?: readonly string[]` Series colors as hex for text output, by series letter (`a` first).
- `format?: 'html' | 'text'` `text` for terminals, or `html` for [`renderToHtml`](https://chartist.dev/packages/terminal/api/#renderToHtml) markup.

## TerminalPieChartOptions

*experimental*

```ts
type TerminalPieChartOptions = Omit<PieChartPresetOptions, 'width' | 'height'> & TerminalChartOptions
```

Options of the terminal [`pieChart`](https://chartist.dev/packages/terminal/api/#pieChart): the options of Chartist's `pieChart` and the terminal options.

Properties:

- `columns?: number` The width in terminal columns.
- `rows?: number` The height in terminal rows.
- `color?: ColorMode` How text output is colored; HTML output uses classes instead.
- `palette?: readonly string[]` Series colors as hex for text output, by series letter (`a` first).
- `format?: 'html' | 'text'` `text` for terminals, or `html` for [`renderToHtml`](https://chartist.dev/packages/terminal/api/#renderToHtml) markup.

## ColorMode

*experimental*

```ts
type ColorMode = 'truecolor' | '256' | '16' | 'none'
```

How text output is colored: 24-bit colors, the 256-color palette, the 16 standard colors, or none (plain text without escape codes).

## ColorStream

```ts
interface ColorStream
```

What [`detectColorMode`](https://chartist.dev/packages/terminal/api/#detectColorMode) reads from an output stream.

Properties:

- `isTTY?: boolean` Whether the stream is a terminal, as `process.stdout.isTTY`.

## LegendOptions

```ts
interface LegendOptions
```

Options of [`legend`](https://chartist.dev/packages/terminal/api/#legend).

Properties:

- `color?: ColorMode` How text output is colored; HTML output uses classes instead.
- `palette?: readonly string[]` Series colors as hex for text output, by series letter (`a` first).
- `columns?: number` The width in columns; entries that don't fit go on the next line.
- `format?: 'html' | 'text'` `text` for terminals, or `html` for markup like [`renderToHtml`](https://chartist.dev/packages/terminal/api/#renderToHtml)'s.