simple-ascii-chart
v5.4.0
Published
Simple ascii chart generator
Maintainers
gtktscReadme
Simple ASCII Chart
Simple ASCII Chart is a TypeScript package for creating customizable ASCII charts in the terminal. It supports two-dimensional data, multiple series, custom colors, and formatters.
Installation
Install the package using yarn (or npm):
yarn add simple-ascii-chart
# or
npm install simple-ascii-chartUsage
In ESM (for example, TypeScript or modern Node.js):
import plot from 'simple-ascii-chart';
// or, if you prefer named imports:
import { plot } from 'simple-ascii-chart';
const graph = plot(input, settings);
console.log(graph);In CommonJS:
// Option 1: access default export
const plot = require('simple-ascii-chart').default;
// Option 2: use named export
const { plot } = require('simple-ascii-chart');
const graph = plot(input, settings);
console.log(graph);CLI
A CLI tool is also available:
Playground
Create charts interactively in the playground.
API Endpoint
Generate charts via the API by sending a POST request with your input data:
curl -d input='[[1,2],[2,3],[3,4]]' -G https://simple-ascii-chart.vercel.app/apiOr pass it as a URL parameter:
https://simple-ascii-chart.vercel.app/api?input=[[1,2],[2,3],[3,4]]&settings={%22width%22:50}Input Format
Input data should be a list of points (single series) or a list of point-lists (multiple series):
type Point = [x: number, y: number];
type Coordinates = Point[] | Point[][];Single series:
const input = [
[1, 1],
[2, 4],
[3, 40],
];Multiple series:
const input = [
[
[0, 18],
[1, 1],
[2, 3],
],
[
[4, 1],
[5, 0],
[6, 1],
],
];Input Types
Point: A single point with x and y coordinates, represented as[x, y].MaybePoint: Allows partial or undefined values within a point, accommodating incomplete data.SingleLine: A series of connected points representing a single line.MultiLine: A collection ofSingleLinearrays for multiple data series.
Configuration (Settings)
Customize plot with the following settings:
Settings Reference
| Option | Description |
|--------|-------------|
| color | Color, Color[], or ColorGetter for series coloring. |
| width | Plot width. |
| height | Plot height. |
| yRange | Y-axis range as [min, max]. Values outside this range are filtered before rendering. |
| showTickLabel | Show full tick labels on the Y-axis. |
| hideXAxis | Hide the X-axis line. |
| hideXAxisTicks | Hide X-axis tick markers and labels. |
| hideYAxis | Hide the Y-axis line. |
| hideYAxisTicks | Hide Y-axis tick markers and labels. |
| customXAxisTicks | Explicit X tick values. |
| customYAxisTicks | Explicit Y tick values. |
| axisCenter | Axis center as [x, y]. Default axis origin is bottom-left. |
| formatter | Axis label formatter: (value, helpers) => string \| number. |
| lineFormatter | Custom point renderer: (args: LineFormatterArgs) => CustomSymbol \| CustomSymbol[]. |
| title | Chart title shown above the plot. |
| xLabel | X-axis label. |
| yLabel | Y-axis label. |
| thresholds | Threshold lines (x and/or y) with optional color. |
| points | Overlay points with optional color. |
| fillArea | Fill area under lines using the area chart symbol. |
| legend | Legend config (position, series, points, thresholds). |
| symbols | Symbol overrides for axis, chart, empty, background, border, thresholds, point. |
| mode | Plot mode: 'line', 'point', 'bar', 'horizontalBar'. |
| debugMode | Enable debug logging for out-of-bounds draw attempts. |
Symbols
Override default symbols. Main sections are axis, chart, thresholds, point, empty, background, and border.
symbols: {
background: '.',
border: undefined,
point: '●',
thresholds: {
x: '━',
y: '┃',
},
empty: ' ',
axis: {
n: '▲',
ns: '│',
y: '┤',
nse: '└',
x: '┬',
we: '─',
e: '▶',
},
chart: {
we: '━',
wns: '┓',
ns: '┃',
nse: '┗',
wsn: '┛',
sne: '┏',
area: '█',
},
}Summary
type Settings = {
color?: Colors; // Colors for the plot lines or areas
width?: number; // Width of the plot
height?: number; // Height of the plot
yRange?: [number, number]; // Range of y-axis values
showTickLabel?: boolean; // Option to show tick labels on the axis
hideXAxis?: boolean; // Option to hide the x-axis
hideXAxisTicks?: boolean; // Option to hide x-axis ticks and labels
hideYAxis?: boolean; // Option to hide the y-axis
hideYAxisTicks?: boolean; // Option to hide y-axis ticks and labels
customXAxisTicks?: number[]; // Custom values for x-axis ticks
customYAxisTicks?: number[]; // Custom values for y-axis ticks
title?: string; // Title of the plot
xLabel?: string; // Label for the x-axis
yLabel?: string; // Label for the y-axis
thresholds?: Threshold[]; // Array of threshold lines
points?: GraphPoint[]; // Array of points to render
fillArea?: boolean; // Option to fill the area under lines
legend?: Legend; // Legend settings
axisCenter?: MaybePoint; // Center point for axes alignment
formatter?: Formatter; // Custom formatter for axis values
lineFormatter?: (args: LineFormatterArgs) => CustomSymbol | CustomSymbol[]; // Custom line formatter
symbols?: Symbols; // Custom symbols for chart elements
mode?: GraphMode; // Graph rendering mode
debugMode?: boolean; // Option to enable debug mode
};Examples
Simple Plot
Input:
plot(
[
[1, 1],
[2, 4],
[3, 4],
[4, 2],
[5, -1],
],
{ width: 9, height: 6 },
);Expected Output:
▲
4┤ ┏━━━┓
│ ┃ ┃
2┤ ┃ ┗━┓
1┤━┛ ┃
│ ┃
-1┤ ┗━
└┬─┬─┬─┬─┬▶
1 2 3 4 5Plot with Title and Custom Size
Input:
plot(
[
[1, 1],
[2, 4],
[3, 4],
[4, 2],
[5, -1],
[6, 3],
[7, -1],
[8, 9],
],
{ title: 'Important data', width: 20, height: 8 },
);Expected Output:
Important data
▲
9┤ ┏━
│ ┃
│ ┃
4┤ ┏━━━━┓ ┃
3┤ ┃ ┃ ┏━┓ ┃
2┤ ┃ ┗━━┓ ┃ ┃ ┃
1┤━━┛ ┃ ┃ ┃ ┃
-1┤ ┗━━┛ ┗━━┛
└┬──┬─┬──┬──┬──┬─┬──┬▶
1 2 3 4 5 6 7 8Plot with Axis Labels
Input:
plot(
[
[1, 1],
[2, 4],
[3, 4],
[4, 2],
[5, -1],
[6, 3],
[7, -1],
[8, 9],
],
{ xLabel: 'x', yLabel: 'y', width: 20, height: 8 },
);Expected Output:
▲
9┤ ┏━
│ ┃
│ ┃
4┤ ┏━━━━┓ ┃
3┤ ┃ ┃ ┏━┓ ┃
y 2┤ ┃ ┗━━┓ ┃ ┃ ┃
1┤━━┛ ┃ ┃ ┃ ┃
-1┤ ┗━━┛ ┗━━┛
└┬──┬─┬──┬──┬──┬─┬──┬▶
1 2 3 4 5 6 7 8
xPlot with Colors
Input:
plot(
[
[
[1, 1],
[2, 2],
[3, 4],
[4, 6],
],
[
[5, 4],
[6, 1],
[7, 2],
[8, 3],
],
],
{
width: 20,
fillArea: true,
color: ['ansiGreen', 'ansiBlue'],
legend: { position: 'bottom', series: ['first', 'second'] },
},
);Expected Output:
▲
6┤ ██
│ ██
4┤ █████ ███
3┤ █████ ███ ██
2┤ ███████ ███ █████
1┤█████████ █████████
└┬──┬─┬──┬──┬──┬─┬──┬▶
1 2 3 4 5 6 7 8
█ first
█ second
Plot with Border
Input:
plot(
[
[1, 1],
[2, 4],
[3, 4],
[4, 2],
[5, -1],
[6, 3],
[7, -1],
[8, 9],
],
{ symbols: { border: '█' }, xLabel: 'x', yLabel: 'y', width: 20, height: 8 },
);Expected Output:
███████████████████████████
█ ▲ █
█ 9┤ ┏━ █
█ │ ┃ █
█ │ ┃ █
█ 4┤ ┏━━━━┓ ┃ █
█ 3┤ ┃ ┃ ┏━┓ ┃ █
█y 2┤ ┃ ┗━━┓ ┃ ┃ ┃ █
█ 1┤━━┛ ┃ ┃ ┃ ┃ █
█ -1┤ ┗━━┛ ┗━━┛ █
█ └┬──┬─┬──┬──┬──┬─┬──┬▶█
█ 1 2 3 4 5 6 7 8 █
█ x █
███████████████████████████Plot with Filled Area
Input:
plot(
[
[
[1, 1],
[2, 2],
[3, 4],
[4, 6],
],
[
[1, 4],
[2, 1],
[3, 2],
[4, 3],
],
],
{
fillArea: true,
color: ['ansiGreen', 'ansiBlue'],
},
);Expected Output:
▲
6┤ ██
│ ██
4┤████
3┤████
2┤████
1┤████
└┬┬┬┬▶
1234Scaled-Up Plot
Input:
plot(
[
[1, 1],
[2, 4],
[3, 40],
[4, 2],
[5, -1],
[6, 3],
[7, -1],
[8, -1],
[9, 9],
[10, 9],
],
{ width: 40, height: 10 },
);Expected Output:
▲
40┤ ┏━━━┓
│ ┃ ┃
│ ┃ ┃
│ ┃ ┃
│ ┃ ┃
│ ┃ ┃
│ ┃ ┃
9┤ ┃ ┃ ┏━━━━━
3┤ ┏━━━━┛ ┗━━━┓ ┏━━━┓ ┃
-1┤━━━┛ ┗━━━━┛ ┗━━━━━━━━┛
└┬───┬────┬───┬───┬────┬───┬───┬────┬───┬▶
1 2 3 4 5 6 7 8 9 10Add Thresholds
Input:
plot(
[
[1, 1],
[2, 4],
[3, 4],
[4, 2],
[5, -1],
[6, 3],
[7, -1],
[8, 9],
],
{
width: 40,
thresholds: [
{
y: 5,
x: 5,
},
{
x: 2,
},
],
},
);Expected Output:
▲ ┃ ┃
9┤ ┃ ┃ ┏━
│ ┃ ┃ ┃
│ ┃ ┃ ┃
│━━━━━┃━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│ ┃ ┃ ┃
4┤ ┃━━━━━━━━━━┓ ┃ ┃
3┤ ┃ ┃ ┃ ┏━━━━┓ ┃
2┤ ┃ ┗━━━━┃ ┃ ┃ ┃
1┤━━━━━┃ ┃ ┃ ┃ ┃
│ ┃ ┃ ┃ ┃ ┃
-1┤ ┃ ┃━━━━━┛ ┗━━━━━┛
└┬─────┬────┬─────┬────┬─────┬────┬─────┬▶
1 2 3 4 5 6 7 8Add Points, Thresholds, and Legend
Input:
plot(
[
[
[1, 2],
[2, -2],
[3, 4],
[4, 1],
],
[
[1, 6],
[2, -3],
[3, 0],
[4, 0],
],
],
{
width: 40,
color: ['ansiGreen', 'ansiMagenta', 'ansiBlack', 'ansiYellow'],
legend: {
position: 'left',
series: ['series 1', 'series 2'],
points: ['point 1', 'point 2', 'point 3'],
thresholds: ['threshold 1', 'threshold 2'],
},
title: 'Points',
thresholds: [
{
y: 5,
x: 2,
color: 'ansiBlue',
},
{
y: 2,
color: 'ansiGreen',
},
],
points: [
{
y: 5,
x: 5,
color: 'ansiBlue',
},
{
y: -1,
x: 1,
color: 'ansiCyan',
},
{
y: 2,
x: 2,
color: 'ansiRed',
},
],
},
);Expected Output:
Points
█ series 1 ▲ ┃
█ series 2 6┤━━━━━━━━━━━━┓┃
│━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━●
┃ threshold 1 4┤ ┃┃ ┏━━━━━━━━━━━━┓
┃ threshold 2 │ ┃┃ ┃ ┃
2┤━━━━━━━━━━━━━●━━━━━━━━━━━━━━━━━━━━━━━━━━━
● point 1 1┤ ┃┃ ┃ ┗━
● point 2 0┤ ┃┃ ┏━━━━━━━━━━━━━━
● point 3 │● ┃┃ ┃
-2┤ ┃┃━━━━━━━━━━━┃
-3┤ ┗┃━━━━━━━━━━━┛
└┬────────────┬────────────┬────────────┬▶
1 2 3 4Add Points Overlay
Input:
plot(
[
[1, 1],
[2, 4],
[3, 4],
[4, 2],
[5, -1],
[6, 3],
[7, -1],
[8, 9],
],
{
width: 40,
title: 'Points',
points: [
{
y: 5,
x: 5,
color: 'ansiBlue',
},
{
y: -1,
x: 1,
color: 'ansiBlue',
},
{
y: 205,
x: 1005,
color: 'ansiBlue',
},
{
y: 2,
x: 2,
color: 'ansiRed',
},
],
},
);Expected Output:
Points
▲
9┤ ┏━
│ ┃
│ ┃
│ ┃
│ ● ┃
4┤ ┏━━━━━━━━━━┓ ┃
3┤ ┃ ┃ ┏━━━━┓ ┃
2┤ ┃● ┗━━━━┓ ┃ ┃ ┃
1┤━━━━━┛ ┃ ┃ ┃ ┃
│ ┃ ┃ ┃ ┃
-1┤● ┗━━━━━┛ ┗━━━━━┛
└┬─────┬────┬─────┬────┬─────┬────┬─────┬▶
1 2 3 4 5 6 7 8Multi-Series Plot
Input:
plot(
[
[
[0, 18],
[1, 1],
[2, 3],
[3, 11],
[4, 5],
[5, 16],
[6, 17],
[7, 14],
[8, 7],
[9, 4],
],
[
[0, 0],
[1, 1],
[2, 1],
[3, 1],
[4, 1],
[5, 0],
[6, 1],
[7, 0],
[8, 1],
[9, 0],
],
],
{ width: 40, height: 10, color: ['ansiBlue', 'ansiGreen'] },
);Expected Output:
▲
17┤━━━━┓ ┏━━━━┓
16┤ ┃ ┏━━━━━┛ ┃
14┤ ┃ ┃ ┗━━━━━┓
11┤ ┃ ┏━━━━━┓ ┃ ┃
│ ┃ ┃ ┃ ┃ ┃
7┤ ┃ ┃ ┃ ┃ ┗━━━━┓
5┤ ┃ ┃ ┗━━━━┛ ┃
4┤ ┃ ┏━━━━┛ ┗━
1┤ ┏━━━━━━━━━━━━━━━━━━━━━┓ ┏━━━━┓ ┏━━━━┓
0┤━━━━┛ ┗━━━━━┛ ┗━━━━━┛ ┗━
└┬────┬─────┬────┬─────┬────┬─────┬────┬─────┬────┬▶
0 1 2 3 4 5 6 7 8 9Plot with Custom Formatter
Input:
plot(
[
[
[0, -10],
[1, 0.001],
[2, 10],
[3, 200],
[4, 10000],
[5, 2000000],
[6, 50000000],
],
],
{
width: 30,
height: 20,
formatter: (n: number, { axis }: FormatterHelpers) => {
const labels = ['A', 'B', 'C', 'D', 'E', 'F', 'G'];
if (axis === 'y') return n;
return labels[n] || 'X';
},
},
);Expected Output:
▲
50000000┤ ┏━
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
2000000┤ ┏━━━━┛
-10┤━━━━━━━━━━━━━━━━━━━━━━━┛
└┬────┬────┬────┬───┬────┬────┬▶
A B C D E F GPlot with Axis Center
Input:
plot(
[
[
[-8, -8],
[-4, -4],
[-3, -3],
[-2, -2],
[-1, -1],
[0, 0],
[2, 2],
[3, 3],
[4, 4],
[8, 8],
],
],
{ width: 60, height: 20, axisCenter: [0, 0] },
);Expected Output:
▲
8┤ ┏━
│ ┃
│ ┃
│ ┃
│ ┃
4┤ ┏━━━━━━━━━━━━━━┛
3┤ ┏━━┛
2┤ ┏━━━┛
│ ┃
┬──────────────┬──┬───┬───┬───0│─────────┬──┬──────────────┬─▶
-8 -4 -3 -2 -1 0│ 2 3 4 8
┏━━-1┤
┏━━━┛ -2┤
┏━━━┛ -3┤
┏━━┛ -4┤
┃ │
┃ │
┃ │
┃ │
━━━━━━━━━━━━━━┛ -8┤
│Plot with Custom Symbols
Input:
plot(
[
[1, 2],
[2, 0],
[3, 5],
[4, 2],
[5, -2],
[6, 3],
],
{
symbols: {
empty: 'x',
background: '-',
axis: {
n: 'A',
ns: 'i',
y: 't',
nse: 'o',
x: 'j',
we: 'm',
e: 'B',
},
chart: {
we: '1',
wns: '2',
ns: '3',
nse: '4',
wsn: '5',
sne: '6',
},
},
width: 40,
height: 10,
},
);Expected Output:
xxA-----------------------------------------
x5t---------------61111112------------------
xxi---------------3------3------------------
xxi---------------3------3------------------
x3t---------------3------3---------------61-
x2t11111112-------3------411111112-------3--
xxi-------3-------3--------------3-------3--
x0t-------411111115--------------3-------3--
xxi------------------------------3-------3--
xxi------------------------------3-------3--
-2t------------------------------411111115--
xxojmmmmmmmjmmmmmmmjmmmmmmjmmmmmmmjmmmmmmmjB
xxx1xxxxxxx2xxxxxxx3xxxxxx4xxxxxxx5xxxxxxx6xPlot without Axes
Input:
plot(
[
[-5, 2],
[2, -3],
[13, 0.1],
[4, 2],
[5, -2],
[6, 12],
],
{
width: 40,
height: 10,
hideYAxis: true,
hideXAxis: true,
},
);Expected Output:
┏━━━━━━━━━━━━━━┓
┃ ┃
┃ ┃
┃ ┃
┃ ┃
┃ ┃
━━━━━━━━━━━━━━┓ ┏━┓ ┃ ┃
┃ ┃ ┃ ┃ ┗━
┃ ┃ ┗━┛
┗━━━━┛Plot with Large Numbers
Input:
plot(
[
[-9000, 2000],
[-8000, -3000],
[-2000, -2000],
[2000, 2000],
[3000, 1500],
[4000, 5000],
[10000, 1400],
[11000, 20000],
[12000, 30000],
],
{
width: 60,
height: 20,
},
);Expected Output:
▲
30k┤ ┏━
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
20k┤ ┏━━┛
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
│ ┃
5k┤ ┏━━━━━━━━━━━━━━━┓ ┃
│ ┃ ┃ ┃
1.4k┤━━┓ ┏━━━━━┛ ┗━━┛
│ ┃ ┃
-2k┤ ┃ ┏━━━━━━━━━━┛
-3k┤ ┗━━━━━━━━━━━━━━━━┛
└┬──┬────────────────┬──────────┬──┬──┬───────────────┬──┬──┬▶
-8k 2k 4k 11k
-9k -2k 3k 10k 12kPlot with Custom Line Formatter
Input:
plot(
[
[1, 0],
[2, 20],
[3, 29],
[4, 10],
[5, 3],
[6, 40],
[7, 0],
[8, 20],
],
{
height: 10,
width: 30,
lineFormatter: ({ y, plotX, plotY, input, index }) => {
const output = [{ x: plotX, y: plotY, symbol: '█' }];
if (input[index - 1]?.[1] < y) {
return [...output, { x: plotX, y: plotY - 1, symbol: '▲' }];
}
return [...output, { x: plotX, y: plotY + 1, symbol: '▼' }];
},
},
);Expected Output:
▲ ▲
40┤ █
│ ▲
29┤ █
│ ▲ ▲
20┤ █ █
│
│
10┤ █
3┤ ▼ █
0┤█ ▼ █
└┬───┬───┬───┬────┬───┬───┬───┬▶
1 2 3 4 5 6 7 8Bar Chart
Input:
plot(
[
[0, 3],
[1, 2],
[2, 3],
[3, 4],
[4, -2],
[5, -5],
[6, 2],
[7, 0],
],
{
title: 'bar chart with axis',
mode: 'bar',
showTickLabel: true,
width: 40,
axisCenter: [0, 0],
},
);Expected Output:
bar chart with axis
▲ █
4┤ █ █
3┤ █ █ █ █
2┤ █ █ █ █
1┤ █ █ █ █ █
0┤─────┬────┬─────┬────┬─────┬────┬─────┬─▶
-1┤ 1 2 3 4 5 6 7
-2┤ █
-3┤ █
-4┤ █
-5┤
│ Horizontal Bar Chart
Input:
plot(
[
[0, 3],
[1, 2],
[2, 3],
[3, 4],
[4, -2],
[5, -5],
[6, 2],
[7, 0],
],
{
mode: 'horizontalBar',
showTickLabel: true,
width: 40,
height: 20,
axisCenter: [3, 1],
},
);Expected Output:
▲
4┤
│
████████████████3┤
│
██████████2┤████████████████
│
┬─────┬────┬────1┤────┬─────┬────┬─────┬─▶
0 1 2 3 4 5 6 7
0┤██████████████████████
│
-1┤
│
-2┤
│█████
-3┤
│
-4┤
│
│
-5┤███████████
│ Support
If this project helps you, consider supporting my open-source work: