@chartist-js/terminal API

Everything is exported from @chartist-js/terminal. Types from chartist link to the Chartist API reference, where Rendering covers the scene and the renderers.

renderToTerminal

Source

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, so its px map to cells.

Parameters

scene SceneNode
options? TerminalRenderOptions = {}

Example

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

Source

function lineChart(data: LineChartData, options: Omit<LineChartPresetOptions, 'width' | 'height'> & TerminalChartOptions & AsElement): HTMLPreElement

function lineChart(data: LineChartData, options?: Omit<LineChartPresetOptions, 'width' | 'height'> & TerminalChartOptions & AsString): string

function lineChart(data: LineChartData, options?: TerminalLineChartOptions): string | HTMLPreElement

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 Omit<LineChartPresetOptions, 'width' | 'height'> & TerminalChartOptions & AsElement

Example

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

Source

function barChart(data: BarChartData, options: Omit<BarChartPresetOptions, 'width' | 'height'> & TerminalChartOptions & AsElement): HTMLPreElement

function barChart(data: BarChartData, options?: Omit<BarChartPresetOptions, 'width' | 'height'> & TerminalChartOptions & AsString): string

function barChart(data: BarChartData, options?: TerminalBarChartOptions): string | HTMLPreElement

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 Omit<BarChartPresetOptions, 'width' | 'height'> & TerminalChartOptions & AsElement

Example

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

Source

function pieChart(data: PieChartData, options: Omit<PieChartPresetOptions, 'width' | 'height'> & TerminalChartOptions & AsElement): HTMLPreElement

function pieChart(data: PieChartData, options?: Omit<PieChartPresetOptions, 'width' | 'height'> & TerminalChartOptions & AsString): string

function pieChart(data: PieChartData, options?: TerminalPieChartOptions): string | HTMLPreElement

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 Omit<PieChartPresetOptions, 'width' | 'height'> & TerminalChartOptions & AsElement

Example

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

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

detectColorMode

Source

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

Example

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

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

CELL_WIDTH

Source

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

Source

const CELL_HEIGHT: 16

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

measureCells

Source

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

Source

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

Source

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.

Parameters

scene SceneNode

Example

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);

renderToElement

Source

function renderToElement(scene: SceneNode, options?: ElementOptions): HTMLPreElement

Renders a scene as HTML text art like renderToHtml, but as a pre element built with DOM methods instead of a string. The markup is the same; a page appends the element and needs no innerHTML, so it works with a Content Security Policy that requires Trusted Types. Throws where there is no document, as in Node.js.

Parameters

scene SceneNode
options? ElementOptions = {}

Example

import { pieChartConfig, toScene } from 'chartist';
import { renderToElement, 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')!.replaceChildren(renderToElement(scene));

legend

Source

function legend(data: LegendData, options: LegendOptions & AsElement): HTMLPreElement

function legend(data: LegendData, options?: LegendOptions & AsString): string

function legend(data: LegendData, options?: LegendOptions): string | HTMLPreElement

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, or an empty pre element, when nothing has a name.

Parameters

data LegendData
options LegendOptions & AsElement

Example

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

Source

interface TerminalRenderOptions

Options of renderToTerminal.

Properties

readonly color? ColorMode: How colors are written; none writes plain text.
readonly 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

Source

interface TerminalChartOptions

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

Properties

readonly columns? number: The width in terminal columns.
readonly rows? number: The height in terminal rows.
readonly color? ColorMode: How text output is colored; HTML output uses classes instead.
readonly palette? readonly string[]: Series colors as hex for text output, by series letter (a first).
readonly format? 'html' | 'text' | 'element': text for terminals, html for renderToHtml markup, or element for the same markup as a pre element (renderToElement), which a page adds without innerHTML.
readonly document? Document: The document element output is created in; the global document by default.

TerminalLineChartOptions

Source

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

Options of the terminal lineChart: the options of Chartist's lineChart and the terminal options.

Properties

readonly columns? number: The width in terminal columns.
readonly rows? number: The height in terminal rows.
readonly color? ColorMode: How text output is colored; HTML output uses classes instead.
readonly palette? readonly string[]: Series colors as hex for text output, by series letter (a first).
readonly format? 'html' | 'text' | 'element': text for terminals, html for renderToHtml markup, or element for the same markup as a pre element (renderToElement), which a page adds without innerHTML.
readonly document? Document: The document element output is created in; the global document by default.

TerminalBarChartOptions

Source

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

Options of the terminal barChart: the options of Chartist's barChart and the terminal options.

Properties

readonly columns? number: The width in terminal columns.
readonly rows? number: The height in terminal rows.
readonly color? ColorMode: How text output is colored; HTML output uses classes instead.
readonly palette? readonly string[]: Series colors as hex for text output, by series letter (a first).
readonly format? 'html' | 'text' | 'element': text for terminals, html for renderToHtml markup, or element for the same markup as a pre element (renderToElement), which a page adds without innerHTML.
readonly document? Document: The document element output is created in; the global document by default.

TerminalPieChartOptions

Source

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

Options of the terminal pieChart: the options of Chartist's pieChart and the terminal options.

Properties

readonly columns? number: The width in terminal columns.
readonly rows? number: The height in terminal rows.
readonly color? ColorMode: How text output is colored; HTML output uses classes instead.
readonly palette? readonly string[]: Series colors as hex for text output, by series letter (a first).
readonly format? 'html' | 'text' | 'element': text for terminals, html for renderToHtml markup, or element for the same markup as a pre element (renderToElement), which a page adds without innerHTML.
readonly document? Document: The document element output is created in; the global document by default.

ColorMode

Source

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

Source

interface ColorStream

What detectColorMode reads from an output stream.

Properties

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

ElementOptions

Source

interface ElementOptions

Options of renderToElement.

Properties

readonly document? Document: The document to create the element in; the global document by default.

LegendOptions

Source

interface LegendOptions

Options of legend.

Properties

readonly color? ColorMode: How text output is colored; HTML output uses classes instead.
readonly palette? readonly string[]: Series colors as hex for text output, by series letter (a first).
readonly columns? number: The width in columns; entries that don't fit go on the next line.
readonly format? 'html' | 'text' | 'element': text for terminals, html for markup like renderToHtml's, or element for the same markup as a pre element, which a page adds without innerHTML.
readonly document? Document: The document element output is created in; the global document by default.