Simple ASCII Chart

Simple ASCII Chart is a TypeScript package for generating ASCII charts in your terminal. It supports multi-dimensional input data, multi-series, custom colors, and formatters to make your data visualization customizable and visually engaging.

Interactive Demo

With color for multiple lines:

With colored area:

With axis positioning:

Installation

Install globally:

npm install -g simple-ascii-chart-cli

Or add it as a project dependency:

yarn add simple-ascii-chart

Then use it in your project:

import plot from 'simple-ascii-chart';

const graph = plot(input, settings);
console.log(graph);

Playground

Try the interactive playground to create and customize graphs online.

API Endpoint

Generate charts programmatically by sending a POST request to the API endpoint with your input data:

curl -d input='[[1,2],[2,3],[3,4]]' -G https://simple-ascii-chart.vercel.app/api

Or as a URL parameter:

https://simple-ascii-chart.vercel.app/api?input=[[1,2],[2,3],[3,4]]&settings={"width":50}

CLI Usage

Run the CLI by passing your data and desired options:

simple-ascii-chart-cli --input '[[1, 2], [2, 3], [3, 4]]' --title "Sample Chart"

CLI Options

| Option | Alias | Type | Description | |-----------------|-------|----------|-------------------------------------------------------------------------------------------------| | --input | -i | string | The data to be plotted (in JSON format). Required. | | --options | -o | string | Additional plot settings (in JSON format). | | --width | -w | number | Width of the plot. | | --height | -h | number | Height of the plot. | | --title | -t | string | Title for the plot. | | --xLabel | | string | Label for the x-axis. | | --yLabel | | string | Label for the y-axis. | | --color | -c | array | Colors for plot elements, specified as ANSI color names. | | --axisCenter | | array | Coordinates for axis center alignment. | | --yRange | | array | Y-axis range in the format [min, max]. | | --showTickLabel| | boolean | Show tick labels on the axis if set to true. | | --thresholds | | array | Array of threshold points or lines with optional color. | | --legend | | string | Legend settings (position and series labels) in JSON format. | | --formatter | | string | Custom formatter function for axis values, as a JavaScript function string. | | --lineFormatter| | string | Function to customize line appearance, as a JavaScript function string. | | --symbols | | string | Custom symbols for axis, chart, and background elements, in JSON format. | | --fillArea | | boolean | Fills the plot area if set to true. | | --hideXAxis | | boolean | Hides the x-axis if set to true. | | --hideYAxis | | boolean | Hides the y-axis if set to true. |

API Reference

Input Data

The input data should be a two-dimensional array. For a single series, provide an array of [x, y] coordinates:

const input = [
  [1, 1],
  [2, 4],
  [3, 8],
];

For multiple series, nest each series inside the main array:

const input = [
  [
    [1, 1],
    [2, 4],
    [3, 8],
  ],
  [
    [1, 2],
    [2, 3],
    [3, 5],
  ],
];

Settings

The plot appearance can be customized with the settings parameter, which accepts the following options:

• color: Array of colors for multiple series, or a single color for one series.
• width: Customizes plot width.
• height: Customizes plot height.
• axisCenter: Sets axis center, default is bottom-left.
• formatter: Formats axis labels. Accepts a Formatter function.
• lineFormatter: Customizes line appearance.
• title: Adds a title above the plot.
• xLabel: Sets label for x-axis.
• yLabel: Sets label for y-axis.
• thresholds: Adds thresholds with optional color.
• fillArea: If true, fills the area below each line.
• hideXAxis: Hides the x-axis if true.
• hideYAxis: Hides the y-axis if true.
• symbols: Customizes symbols for chart, axis, and background.

Example Usage

Create and display a simple plot with a title:

plot(
  [
    [1, 2],
    [2, 4],
    [3, 6],
  ],
  { title: 'Sample Data', width: 10, height: 6 }
);

Output:

Sample Data
   ▲
  6┤  ┏━
   │  ┃
  4┤  ┃
  2┤━━┛
   └─▶
    1 2 3

Plot with Multiple Series and Colors

plot(
  [
    [
      [1, 1],
      [2, 4],
      [3, 9],
    ],
    [
      [1, 3],
      [2, 6],
      [3, 3],
    ],
  ],
  { color: ['ansiRed', 'ansiBlue'], width: 15, height: 7 }
);

Examples

This README includes various examples with plots for titles, multi-series data, axis labels, area filling, custom symbols, and more.

For any questions or additional details, see the documentation.