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:

| name | description | type | default | | ----- | ----------- | ------ | ------------- | | label | bar label | string | point.value | | value | bar value | number | N/A | | color | bar color | string | options.color |

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

| name | description | type | default | | ----------- | ----------------------------------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------- | | percentage | calculate and show percentage data | boolean | false | | colorLabels | color labels with provided color per label, or color provided to option | boolean | false | | valueLabels | show values of each bar | boolean | true | | sort | sort the input data | boolean | false | | reverse | reverse the input data | boolean | false | | naked | don’t print chart structure ascii characters | boolean | false | | labels | show labels | boolean | true | | color | fallback color or unified char bars color | string | undefined | | fill | use this character to fill remaining chart bar space | string | undefined | | scale | values are scaled proportionate to this value. otherwise the max will be calculated from the provided data. | number or string | auto | | width | width of chart | number | 100 | | height | height of chart | number | 10 | | padding | padding between bars | number | 0 | | barSize | size of each bar | number | 1 | | title | chart title | string | undefined | | char | use this character to draw the chart bars | string | █ | | orientation | horizontal or vertical | string | horizontal | | theme | styl3's themes | string | undefined | | structure | use these characters to draw the enclosing chart borders. | object | { x: '═', y: '╢', bottomLeft: '╚', axis: '║', topLeft: '╔' } |

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.