**Render your data as beautiful ASCII charts**
with full color, gradients, stacked bars, animations, and rich text, straight from your terminal.
[](https://www.npmjs.com/package/chartscii)
[](https://www.npmjs.com/package/chartscii)
[](./LICENSE)
That's it — three lines of data, one chart object, and a single `console.log` call.
---
## Chart types
Set the `type` option to switch the renderer. Every chart type shares the core options (`width`, `height`, `title`, `theme`, `color`, `naked`, …) and adds its own visual model and a few type-specific knobs.
| Type | Best for | Key options |
|---|---|---|
| [`bar`](#bar-default) (default) | categorical comparisons, totals, rankings | `orientation`, `alignBars`, `stackColors` |
| [`line`](#line) | trends over time, multiple series | `points`, `pointChar`, `legend` |
| [`step`](#step) | state changes between samples | `variant: 'sharp' \| 'smooth'`, `points` |
| [`scatter`](#scatter) | sparse points, distributions | `pointChar`, `colorLabels` |
| [`candlestick`](#candlestick) | OHLC market data | `color: [bull, bear]`, `barSize` |
| [`status`](#status) | dashboards, health grids | `color: { key → color }`, grid or row mode |
### Bar (default)
The classic chartscii renderer. Stacked, oriented, and aligned to taste.
```typescript
const chart = new Chartscii([10, 25, 40, 15], {
type: "bar",
orientation: "vertical",
color: "gradient(cyan,purple)",
});
```
### Line
Smooth 45° polyline through your data. Single- or multi-series, with optional point markers.
```typescript
const chart = new Chartscii(data, {
type: "line",
width: 80,
height: 12,
color: "gradient(pink,cyan)",
fill: "░", // optional area fill below the line
fillColor: "pink",
points: true, // draw a marker at each data point
pointChar: "◈", // override the marker char
});
```
**Multi-series:** pass `InputData[][]` and an array of colors.
```typescript
const chart = new Chartscii(seriesData, {
type: "line",
width: 150,
color: ["gradient(pink,cyan)", "gradient(orange,yellow)", "red"],
legend: { values: ["Q1", "Q2", "Q3"], position: "top", align: "right" },
});
```
> Slopes that need more horizontal space than the natural 45° span are clustered into a single contiguous diagonal followed by a flat plateau, so peaks render as sharp `╱╲` rather than a jagged staircase.
### Step
Same idea as `line`, but transitions are right-angle steps — perfect for state that's piecewise-constant between samples.
```typescript
const chart = new Chartscii(data, {
type: "step",
width: 80,
variant: "smooth", // 'sharp' (┌┐└┘) or 'smooth' (╭╮╰╯)
color: "auto",
points: true,
});
```
Multi-series and `legend` work exactly like `line`:
### Scatter
Just the points — no connecting line. Each marker can be a different color.
```typescript
const chart = new Chartscii(data, {
type: "scatter",
width: 100,
color: "auto", // cycle the palette per point
pointChar: "◈", // default '●'
colorLabels: true, // tint x-axis labels with their point's color
});
```
Per-point overrides win over the series color, so `{ value, color }` colors that specific marker:
### Candlestick
OHLC bars with bullish / bearish coloring. Each input point's `value` is a 4-tuple `[open, high, low, close]`.
```typescript
const chart = new Chartscii(month, {
type: "candlestick",
width: 100,
height: 18,
color: ["#4caf50", "#ef5350"], // [bullish, bearish]
// color: "auto", // also valid — uses theme bull/bear pair
title: { text: "BTC/USD — 30d", align: "center", color: "gradient" },
legend: { position: "top", align: "right" },
});
```
`barSize` controls the body width (default `1` — a one-cell-wide candle); `padding` controls the gap between candles. Doji candles (`open == close`) render as `─`.
### Status
A grid (or row layout) of colored cells — perfect for dashboards, host health, build matrices, log heatmaps, and so on. Each cell's `value` is a status key (number or string) looked up in the `color` map.
```typescript
// Grid mode — one cell per input
const chart = new Chartscii(fleet, {
type: "status",
width: 100,
barSize: 5,
padding: 1,
color: {
0: "red", // down
1: "green", // ok
2: "yellow", // warning
3: "#888", // maintenance
},
legend: { values: ["down", "ok", "warning", "maintenance"] },
});
```
Pass `value: number[]` (or `string[]`) on any input point to switch into **row mode** — each input becomes a row labelled on the left, with its array values rendered as colored cells along the x-axis:
```typescript
const data: InputData[] = [
{ value: [1, 1, 0, 1, 2, 1, 1], label: "web1" },
{ value: [1, 0, 0, 1, 1, 1, 2], label: "web2" },
{ value: [1, 1, 1, 1, 1, 1, 1], label: "web3" },
];
```
> Mixed input is allowed — scalar `value`s become single-cell rows. Per-point `color` overrides apply to every cell on that row.
---
## Input formats
### Simple numbers
```typescript
const chart = new Chartscii([1, 2, 3, 4, 5]);
```
### Chart points
```typescript
const data = [
{ label: "Sales", value: 100, color: "green" },
{ label: "Returns", value: 25, color: "red" },
{ label: "Pending", value: 40, color: "yellow" },
];
```
| Property | Type | Description |
|---|---|---|
| `label` | `string` | Bar / point label (defaults to value) |
| `value` | `number` \| `number[]` \| `string` | Single, stacked, OHLC, or status key — see below |
| `color` | `string` \| `string[]` | Color or per-segment colors |
### Chart-type-specific value shapes
| Chart type | `value` shape |
|---|---|
| `bar`, `line`, `step`, `scatter` | `number` |
| Stacked `bar` | `number[]` or `{ value, color? }[]` |
| `candlestick` | `[open, high, low, close]` (number tuple) |
| `status` (grid mode) | `number` \| `string` (status key) |
| `status` (row mode) | `number[]` \| `string[]` (one cell per entry) |
### Multi-series (line / step / scatter)
Pass `InputData[][]` — one inner array per data point, with one entry per series:
```typescript
const data: InputData[][] = months.map((m, i) => [
{ value: salesA[i], label: m }, // series 1
{ value: salesB[i], label: m }, // series 2
]);
```
---
## Styling
### Colors & gradients
`color` accepts a few different shapes depending on the chart type:
```typescript
// Any chart — a single color, a gradient, or "auto" palette cycling
color: "green"
color: "gradient(pink,cyan)"
color: "auto"
// Multi-series line / step / scatter — one entry per series
color: ["gradient(pink,cyan)", "gradient(orange,yellow)", "red"]
// Candlestick — [bullish, bearish]
color: ["green", "red"]
// Status — map from status key to color
color: { 0: "red", 1: "green", 2: "yellow", 3: "#888" }
color: { ok: "green", warning: "yellow", error: "red" }
```
#### Auto color
Cycle through a curated palette automatically — no manual color assignments needed.
```typescript
const data = Array.from({ length: 9 }, (_, i) => ({
value: (i + 1) * 5,
label: `item ${i + 1}`,
}));
const chart = new Chartscii(data, {
width: 50,
color: "auto",
colorLabels: true,
valueLabels: true,
theme: "pastel",
});
```
#### Gradient directions
```typescript
// Horizontal — left to right
color: "gradient(red,yellow,green)";
// Vertical — top to bottom
color: "gradient(purple,cyan:vertical)";
// Diagonal — corner to corner
color: "gradient(pink,orange,yellow:diagonal)";
// Any direction can be reversed
color: "gradient(purple,cyan:vertical:reverse)";
color: "gradient(pink,orange,yellow:diagonal:reverse)";
```
```typescript
const chart = new Chartscii(data, {
width: 60,
title: {
text: "Gradient Aligned Right",
align: "right",
color: "gradient",
padding: [1, 0],
},
orientation: "vertical",
color: "gradient(pink,cyan)",
theme: "beach",
fill: "░",
fillColor: "auto",
padding: 1,
valueLabels: true,
});
```
#### Reverse gradient
```typescript
const chart = new Chartscii(data, {
orientation: "vertical",
barSize: 10,
fill: "▒",
fillColor: "auto",
colorLabels: true,
color: "gradient(pink,cyan:reverse)",
theme: "pinkish",
percentage: true,
});
```
### Themes
Chartscii integrates with [styl3](https://github.com/tool3/styl3) for 20+ built-in color themes. Just set the theme name:
```typescript
const chart = new Chartscii(data, { theme: "lush" });
```
| Theme | Vibe |
|---|---|
| `pastel` | Soft, muted tones |
| `lush` | Vibrant, saturated |
| `beach` | Warm coastal palette |
| `neon` | Electric, bright |
| `sunset` | Warm orange/red tones |
| `nature` | Earthy greens |
| `mint` | Cool mint/teal |
See all themes in the [styl3 docs](https://github.com/tool3/styl3/tree/master?tab=readme-ov-file#themes).
### Fills
Fill the empty space below bars or under a line:
```typescript
const chart = new Chartscii(data, {
fill: "░", // any character
fillColor: "auto", // or a specific color, gradient, or "auto"
});
```
---
## Layout
### Orientation
Bar charts can be horizontal (default) or vertical:
```typescript
const chart = new Chartscii(data, {
orientation: "vertical", // 'horizontal' | 'vertical'
});
```
### Bar alignment
#### Horizontal alignment
```typescript
const chart = new Chartscii(data, {
width: 80,
padding: 1,
alignBars: "center", // 'top' | 'center' | 'bottom' | 'justify'
color: "auto",
theme: "beach",
});
```
| top | bottom | center | justify |
|---|---|---|---|
|  |  |  |  |
#### Vertical alignment
```typescript
const chart = new Chartscii(data, {
orientation: "vertical",
width: 80,
padding: 1,
alignBars: "justify", // 'left' | 'center' | 'right' | 'justify'
color: "auto",
theme: "beach",
});
```
| left | right | center | justify |
|---|---|---|---|
|  |  |  |  |
### Title
Titles support text, alignment, padding, and color (including gradient):
```typescript
const chart = new Chartscii(data, {
orientation: "vertical",
title: {
text: "Aligned",
align: "right", // 'center' | 'left' | 'right'
padding: [2, 0], // CSS-style: [topBottom, leftRight] | [t, r, b, l] | number
color: "gradient", // follow chart gradient — or supply your own ('gradient(blue,pink)')
},
width: 80,
color: "gradient(cyan,purple)",
fill: "▒",
fillColor: "auto",
theme: "pastel",
alignBars: "justify",
});
```
| left | center | right |
|---|---|---|
|  |  |  |
---
## Labels
### Value labels
Show values on the bars — including segment values for stacked bars:
```typescript
const chart = new Chartscii(data, {
valueLabels: true,
valueLabelsFloatingPoint: 2, // optional decimal precision
});
```
### Custom formatters
Full control over labels and value labels with custom format functions:
```typescript
const data = Array.from({ length: 10 }, (_, i) => i + 1);
const chart = new Chartscii(data, {
fill: "░",
labelFormat: (label) => `\x1b[7mlabel ${label}`,
fillColor: "auto",
padding: 1,
theme: "beach",
valueLabels: true,
orientation: "vertical",
color: "gradient(lime,purple)",
});
```
### Rich text labels
Use [styl3](https://github.com/tool3/styl3) decorators directly inside labels — `*bold*`, `%italic%`, `!underline!`, `@invert@`:
```typescript
const data = [
{ value: 10, label: "*bold* Sales", color: "green" },
{ value: 5, label: "%italic% Returns", color: "red" },
{ value: 8, label: "!underline! Pending", color: "yellow" },
{ value: 3, label: "@invert@ Cancelled", color: "purple" },
];
const chart = new Chartscii(data, {
barSize: 16,
theme: "pastel",
alignBars: "justify",
orientation: "vertical",
stackColors: ["red", "orange", "yellow"],
});
```
---
## Stacked bars
Visualize multi-dimensional data with stacked segments. Works in both orientations.
### Vertical
```typescript
const data: InputData[] = [
{ label: "Mon", value: [5, 10, 5] },
{ label: "Tue", value: [7, 3, 10] },
{ label: "Wed", value: [10, 6, 4] },
{ label: "Thu", value: [3, 6, 11] },
{ label: "Fri", value: [8, 6, 6] },
{ label: "Sat", value: [11, 5, 6] },
{ label: "Sun", value: [9, 6, 5] },
];
const chart = new Chartscii(data, {
height: 10,
width: 50,
padding: 5,
theme: "pastel",
orientation: "vertical",
alignBars: "justify",
stackColors: ["red", "orange", "yellow"],
});
```
### Horizontal
```typescript
const chart = new Chartscii(data, {
barSize: 2,
width: 60,
padding: 1,
theme: "pastel",
alignBars: "justify",
colorLabels: true,
color: "green",
stackColors: ["green", "pink", "blue"],
});
```
### Stacked value-label formatting
`valueLabelFormat` receives an array of segment labels, so you can format them however you like:
```typescript
const data: InputData[] = [
{ label: "Jan", value: [2, 8] },
{ label: "Feb", value: [1, 9] },
{ label: "Mar", value: [3, 7] },
{ label: "Apr", value: [6, 4] },
{ label: "May", value: [3, 7] },
{ label: "Jun", value: [9, 1] },
{ label: "Jul", value: [4, 6] },
];
const chart = new Chartscii(data, {
barSize: 2,
width: 60,
padding: 2,
alignBars: "justify",
color: "gradient(#72cac6,#CA7276)",
valueLabels: true,
valueLabelFormat: (values) => values.map((v) => Number(v) / 10).join(" / "),
stackColors: ["#72cac6", "#CA7276"],
});
```
### Auto-colored stacks
Stacked charts also support `color: "auto"` for palette cycling per segment:
…and partial overrides — set `color` on a specific data point to override that point's segments:
```typescript
const data: InputData[] = [
// ...
{ label: "Thu", value: [3, 6, 11], color: ["cyan", "pink", "purple"] },
// ...
];
```
---
## Animation
Create smooth terminal animations with built-in easings:
```typescript
const data = Array.from({ length: 20 }, (_, i) => ({
value: Math.round(Math.sin(i / 3) * 10 + 15),
label: `${i}`,
}));
const chart = new Chartscii(data, {
width: 60,
title: {
text: "Gradient Aligned Center",
align: "center",
color: "gradient",
},
orientation: "vertical",
color: "gradient(pink,cyan)",
theme: "beach",
fill: "░",
padding: 1,
fillColor: "auto",
valueLabelsFloatingPoint: 0,
valueLabels: true,
});
chart.animate({ duration: 1500, easing: "easeInOut", fps: 60 });
```
### Manual frames
Drive your own loop and re-render in place using `\x1B[H` to reset the cursor:
```typescript
const frames = 120;
for (let frame = 0; frame < frames; frame++) {
const data = Array.from({ length: 40 }, (_, i) => {
const value = Math.sin((i + frame) / 4) * 10 + 12;
return { value: Math.round(value), label: "" };
});
const chart = new Chartscii(data, {
orientation: "vertical",
height: 24,
naked: true,
labels: false,
color: "gradient(cyan,purple,pink:vertical)",
fill: "░",
fillColor: "auto",
});
process.stdout.write("\x1B[H" + chart.create());
}
```
---
## Configuration reference