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