ink-uplot

Render uPlot charts in the terminal with React Ink. Reuse your existing browser uPlot config — series, axes, scales — and get pixel-accurate, truecolor terminal charts. Auto-detects the best output for your terminal: Unicode block art, or native kitty / sixel / iTerm2 graphics protocols for real inline images.

A terminal charting / TUI dataviz library for Node.js — line charts, time series, live-updating dashboards, and trading-style plots, straight in your CLI.

Why ink-uplot?

• Real uPlot config, not a new API — paste the same opts/data you'd use in the browser. Series, scales, dual axes, custom tick formatters all work.
• Truecolor & graphics protocols — beyond ASCII/Unicode: emit real images via the kitty, sixel, and iTerm2 inline-image protocols, auto-detected per terminal.
• Built for live data — update the data prop to animate; designed for streaming, real-time dashboards.
• Composable — it's a normal Ink <Box>/<Text> component; embed it in any TUI layout.
• TypeScript-first, ESM, fully typed.

Install

npm install ink-uplot uplot ink react

uplot, ink, and react are peer dependencies. canvas (node-canvas) is pulled in automatically but needs system libraries (Cairo, Pango):

• macOS: brew install pkg-config cairo pango
• Debian/Ubuntu: sudo apt-get install build-essential libcairo2-dev libpango1.0-dev
• See node-canvas compiling for other platforms.

Quick Start

import React from 'react';
import { render } from 'ink';
import { InkUPlot } from 'ink-uplot';

const opts = {
  series: [
    {},
    { stroke: 'cyan', label: 'Price', width: 2 },
  ],
  axes: [
    { stroke: '#555', grid: { stroke: '#333' } },
    { stroke: '#555', grid: { stroke: '#333' } },
  ],
};

const data = [
  [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],           // x values
  [10, 25, 15, 30, 20, 35, 25, 40, 30, 45],  // y values
];

function App() {
  return <InkUPlot opts={opts} data={data} width={80} height={24} />;
}

render(<App />);

Terminal formats

ink-uplot picks the highest-fidelity output your terminal supports and falls back gracefully. Detection is automatic (detectFormat()), or force one with the format prop.

| Format | What it is | Terminals | |--------|-----------|-----------| | symbols | Truecolor Unicode block art (via chafa) | Any terminal — universal fallback | | kitty | kitty graphics protocol | kitty, Ghostty, Konsole | | sixels | Sixel graphics | foot, Windows Terminal, xterm (+sixel) | | iterm2 | iTerm2 inline images | iTerm2, WezTerm, VS Code |

// Force a format instead of auto-detecting:
<InkUPlot opts={opts} data={data} format="symbols" />

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | opts | uPlot.Options | required | Standard uPlot options. Interactive options (cursor, select, legend) are stripped automatically. | | data | uPlot.AlignedData | required | uPlot data array — identical to browser uPlot. | | width | number | stdout.columns or 80 | Chart width in terminal columns. | | height | number | 24 | Chart height in terminal rows. | | format | 'symbols' \| 'kitty' \| 'sixels' \| 'iterm2' | auto-detected | Output format for the current terminal. | | showAxes | boolean | true | Render text axes around the chart. false for a borderless chart. | | color | boolean | true | Enable truecolor ANSI output. |

Features

• Truecolor rendering — 24-bit color Unicode block art, or real inline images via graphics protocols.
• Text axes — Y-axis labels (left and/or right) and X-axis ticks render as real, copy-pasteable text.
• Dual Y-axis — put scales on the left, right, or both via uPlot's scale and side config.
• Timestamp auto-detection — unix-timestamp X values are formatted as dates automatically.
• Custom axis formatters — set values on an axis to control tick labels (e.g. mm:ss).
• Live / streaming data — update the data prop to animate; resize-aware.
• Responsive — follows terminal resize when width isn't fixed.

Examples

Run any example with npx tsx examples/<name>.tsx. Press q to quit.

| Example | Description | |---------|-------------| | basic-line.tsx | Simple sine wave with axes | | multi-series.tsx | Three overlapping series | | dual-y-axis.tsx | Price (left) + Volume (right) Y-axis | | shaded-area.tsx | Area charts with translucent fill | | timestamps.tsx | 90-day time series with date X-axis | | live-trading.tsx | Streaming data at 100ms, mm:ss X-axis, highlighted last value | | no-axes.tsx | Minimal borderless chart (showAxes={false}) | | line-width-test.tsx | Interactive line-width comparison (arrow keys) |

How it works

1. A minimal DOM shim provides fake document/window globals so uPlot can initialize in Node.js.
2. uPlot renders your series onto a node-canvas instance.
3. The canvas pixel buffer is extracted (getImageData, or a native PNG for iTerm2).
4. For symbols/kitty/sixels, chafa-wasm converts pixels to truecolor terminal output; for iterm2 the PNG is sent inline.
5. Text axes are computed separately (nice-numbers tick algorithm) and rendered as Ink <Text>.
6. Everything is composed via Ink <Box>/<Text> layout.

Lower-level API

For custom pipelines, the internals are exported:

import {
  renderToImageData,
  renderToPNG,
  pixelsToTerminal,
  detectFormat,
} from 'ink-uplot';

// uPlot → pixel buffer
const imageData = await renderToImageData(opts, data, 640, 384);

// pixels → terminal output (symbols / kitty / sixels)
const ansi = await pixelsToTerminal(imageData, { width: 80, height: 24, colors: 'truecolor' });
console.log(ansi);

// uPlot → PNG buffer (used by the iTerm2 fast path)
const png = await renderToPNG(opts, data, 640, 384);

Tips

• Series colors: high-contrast colors ('cyan', '#ff0000', '#00ff88') read best.
• Embedding: the component occupies exactly its width × height in cells — wrap it in an Ink <Box> to place it in a larger layout.
• Shaded areas: use fill with alpha ≥ 0.3 (e.g. 'rgba(0, 200, 255, 0.4)'); very low alpha may not be visible.
• Formats: if a terminal misdetects, pass format explicitly. symbols works everywhere.

Used by

• glassnode-terminal — an interactive terminal UI for exploring Glassnode on-chain & market crypto data: a three-pane explorer with live charts and price tickers.

Using ink-uplot in your project? Open a PR to add it here.

Requirements

• Node.js >= 18
• System libraries for node-canvas (Cairo, Pango)

License

MIT