Updated May 2026Edit this page ↗

Chart Widgets

Data visualization widgets in @termuijs/widgets render charts entirely in the terminal using Unicode block characters, with ASCII fallbacks for CI environments.

BarChart

Grouped horizontal or vertical bar chart:

○TYPESCRIPT
import { BarChart } from '@termuijs/widgets'
import type { BarGroup } from '@termuijs/widgets'
 
const data: BarGroup[] = [
    { label: 'Jan', bars: [{ value: 42, color: { type: 'named', name: 'cyan' } }] },
    { label: 'Feb', bars: [{ value: 67 }] },
    { label: 'Mar', bars: [{ value: 55 }] },
]
 
const chart = new BarChart(data, { flexGrow: 1 }, {
    orientation: 'vertical',
    maxValue: 100,
})

For grouped bars, include multiple items in the bars array:

○TYPESCRIPT
const grouped: BarGroup[] = [
    {
        label: 'Q1',
        bars: [
            { value: 42, color: { type: 'named', name: 'cyan' }   },  // read
            { value: 31, color: { type: 'named', name: 'green' }  },  // write
        ],
    },
]
BarGroup fieldTypeDescription
labelstringX-axis label for this group
barsArray<\{ value: number, color?: Color \}>One bar per series
BarChart optionTypeDefaultDescription
orientation'horizontal' \| 'vertical''vertical'Direction of bars
maxValuenumberAuto (max of data)Top of the scale
showLabelsbooleantrueShow axis labels

Sparkline

A compact inline trend line for time-series data. Fits in a single row:

○TYPESCRIPT
import { Sparkline } from '@termuijs/widgets'
 
const spark = new Sparkline('CPU', { height: 1, flexGrow: 1 }, {
    color: { type: 'named', name: 'green' },
})
spark.setData([12, 24, 18, 45, 67, 52, 41])

The widget auto-scales to fit the data range into the available width. When NO_UNICODE=1, uses numeric ASCII characters (1–8) as level indicators instead of block characters.

LineChart

An ASCII line plot with labeled X and Y axes:

○TYPESCRIPT
import { LineChart } from '@termuijs/widgets'
 
const chart = new LineChart({ flexGrow: 1 }, {
    series: [
        { data: [10, 20, 35, 28, 42, 38, 55], label: 'Requests', color: { type: 'named', name: 'cyan' } },
        { data: [2,  5,  8,  6,  12, 10, 18], label: 'Errors',   color: { type: 'named', name: 'red' }  },
    ],
    xLabels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
    xLabel: 'Day',
    yLabel: 'Count',
    showAxes: true,
})

Plot characters used:

  • ● — data point
  • ╱ — positive slope
  • ╲ — negative slope
  • ─ — flat segment

When NO_UNICODE=1, falls back to: *, /, \, -.

Series fieldTypeDescription
datanumber[]Y values for each X position
labelstringLegend label
colorColorLine color
LineChart optionTypeDefaultDescription
seriesSeriesData[]RequiredOne or more data series
xLabelsstring[]—Labels for each X position
xLabelstring—X axis title
yLabelstring—Y axis title
showAxesbooleantrueRender axis lines and labels
minYnumberAutoForce Y axis minimum
maxYnumberAutoForce Y axis maximum

HeatMap

A 2D matrix visualization with a cool-to-warm color gradient:

○TYPESCRIPT
import { HeatMap } from '@termuijs/widgets'
 
// 24-hour × 7-day activity grid
const data = Array.from({ length: 7 }, () =>
    Array.from({ length: 24 }, () => Math.random() * 100)
)
 
const map = new HeatMap({ flexGrow: 1 }, {
    data,
    rowLabels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
    colLabels: Array.from({ length: 24 }, (_, i) => `${i}h`),
})

Shading characters (unicode): ░ ▒ ▓ █ — lighter = lower value, darker = higher. ASCII fallback (when NO_UNICODE=1): . : # @.

HeatMap optionTypeDescription
datanumber[][]Row-major 2D matrix of values
rowLabelsstring[]Label for each row (left side)
colLabelsstring[]Label for each column (top)
colorScale[Color, Color]Start and end colors for the gradient (default: blue → red)

See also

← PreviousLayoutNext →Feedback