chartscii v3.0.1

Chartscii 3.0!

for command line usage see: chartscii-cli

Chartscii was rewritten from scratch in TypeScript! It includes many new features, improvements and rich formatting capabilities.

What’s new

✅ Full width and height control.
✅ New padding and barSize options!
✅ New orientation option! vertical charts are here!
✅ New rich styl3 formatting support!
✅ New Emoji characters support! *

install

npm install chartscii

usage

chartscii accepts an array of data objects, with optional labels, and outputs an ascii bar chart.

usage example

import Chartscii from "chartscii";

const data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
const options = {
  title: "chartscii",
  width: 50,
  theme: "pastel",
  color: "pink",
  colorLabels: true,
  barSize: 2,
  orientation: "vertical"
};
const chart = new Chartscii(data, options);
console.log(char.create());

Input

Chartscii accepts an array of data points to draw the chart.

This can be an array of numbers, or an array of chart points as explained below.

number[]

If you provide an array of numbers, chartscii will draw each bar using the provided values.

Value is scaled to width/height of chart, depending on the orientation option.

example

import Chartscii from "chartscii";

const data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
const chart = new Chartscii(data);
console.log(chart.create());

ChartPoint[]

For maximum flexibility, provide an array of chart points. This will allow you to customize the following properties:

example

import Chartscii from 'chartscii';

const data = [{ label: 'label', value: 2, color: 'pink' }, { label: 'label', value: 2, color: 'purple' }, { label: 'label', value: 2, color: 'marine' },];
const chart = new Chartscii(data, { colorLabels: true });
console.log(chart.create());

Options

You can customize the look and size of the chart, as well as rich formatting for labels provided by styl3.

default options

Chartscii accepts customization options as a second argument and will merge the provided options with the following one:

const options: ChartOptions = {
  percentage: false,
  colorLabels: false,
  sort: false,
  reverse: false,
  naked: false,
  labels: true,
  color: undefined,
  fill: undefined,
  width: 100,
  height: 10,
  padding: 0,
  barSize: 1,
  title: "",
  char: "█",
  orientation: "horizontal",
  theme: "",
  structure: {
    x: "═",
    y: "╢",
    axis: "║",
    topLeft: "╔",
    bottomLeft: "╚"
  }
};

customization options

chartscii + styl3 = ❤️

You can use styl3’s formatting for cool themes, built-in color names and rich label formatting.

You should check out styl3 for a full list of customization options.

example

const colors = [
  "red",
  "green",
  "yellow",
  "blue",
  "purple",
  "pink",
  "cyan",
  "orange"
];

const data = [];
for (let i = 0; i < colors.length; i++) {
  const color = colors[i];
  data.push({ value: i + 1, color, label: `@invert ${i}@`, theme: "pastel" });
}

const chart = new Chartscii(data, {
  fill: "░",
  colorLabels: true,
  orientation: "vertical"
});

console.log(chart.create());

examples

here are some examples of charts using styl3's formatting on the chart labels.

!TIP
you can run more examples from the ./examples/ directory of this repository using ts-node.
for example npx ts-node examples/loaders.ts

vertical

options	chart
beach theme with italic and bold labels with a bar size of 2
pastel theme with bold and underlined labels with padding of 2
lush theme with strikedout labels no padding and emoji
lush theme with underlined labels no padding and no axis structure char
standard theme with dimmed and italic labels and padding 1
pastel theme with inverted and underlined labels with a dark fill character

horizontal

options	chart
pastel theme with bold labels and percentage
lush theme with inverted labels and naked chart
beach theme with underlined labels and different structure characters
pastel theme with padding of 1 and custom char
pastel theme with naked chart - can be used to create loaders

Unicode issues

Unfortunately, there are some known issues with specific unicode characters width.
This means that some emoji/unicode characters renders as 2 characters wide (or more) instead of 1, which is not a problem in itself.
The problem is that Javscript determines this length as 1, which creates an issue with label alignment, or drawing the chart bars correctly.

!WARNING
If you have issues with label alignment, or the chart bars aren't spaced correctly - you are probably using an emoji/unicode character which produce the wrong width in javascript.

If you encounter this issue unfortunately the current solution is to simply use a different emoji.
(For example: 🔥 works well while ✅ will result in a misaligned chart).
PRs for this problem are more than welcome.