A dynamic, real-time ASCII-based vertical bar chart library that renders beautiful terminal-style visualizations using monospaced characters. Perfect for dashboards, monitoring tools, or any application that needs lightweight, text-based data visualization.

Features

📊 Real-time Updates: Add data points dynamically and watch the chart animate
📏 Auto-scaling: Y-axis automatically adjusts to show min/max values
🔤 Monospaced Rendering: Uses 'X' characters in Courier font for clean visualization
📱 Responsive: Automatically adjusts font size to fit container width
🏷️ Customizable Labels: Add title, X-axis, and vertical Y-axis labels
🎯 Scrolling Data: Old data automatically scrolls off as new data arrives
🎨 Terminal Theme: Retro green-on-black aesthetic

Demo

                    Real-Time Data Visualization

  486 |                                                         X  
  484 |                                                         X X
  482 |                                                   X     X X
  481 |                                                   X     X X
  479 |                                             X X   X X X X X
  477 |                                             X X X X X X X X
  475 |                                           X X X X X X X X X
C 473 |                                       X   X X X X X X X X X
o 472 |                                   X X X X X X X X X X X X X
u 470 |                             X X   X X X X X X X X X X X X X
n 468 |                             X X X X X X X X X X X X X X X X
t 466 |                     X     X X X X X X X X X X X X X X X X X
  465 |                 X   X   X X X X X X X X X X X X X X X X X X
  463 |           X     X X X X X X X X X X X X X X X X X X X X X X
  461 |           X     X X X X X X X X X X X X X X X X X X X X X X
  459 |     X     X     X X X X X X X X X X X X X X X X X X X X X X
  457 |   X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
  456 |   X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
  454 |   X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
  452 | X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X
      +------------------------------------------------------------
       453        458        463        468        473        478        

                              Time (seconds)

Installation

Simply include the JavaScript file in your HTML:

<script src="text_graph.js"></script>

Quick Start

<!DOCTYPE html>
<html>
<head>
    <style>
        #chart {
            font-family: 'Courier New', monospace;
            background: #000;
            color: #0f0;
            padding: 20px;
            white-space: pre;
        }
    </style>
</head>
<body>
    <div id="chart"></div>
    
    <script src="text_graph.js"></script>
    <script>
        // Create chart
        const chart = new ASCIIBarChart('chart', {
            maxHeight: 20,
            maxDataPoints: 30,
            title: 'My Chart',
            xAxisLabel: 'Time',
            yAxisLabel: 'Value'
        });
        
        // Add data
        chart.addValue(15);
        chart.addValue(23);
        chart.addValue(18);
    </script>
</body>
</html>

API Reference

Constructor

new ASCIIBarChart(containerId, options)

Creates a new ASCII bar chart instance.

Parameters:

Parameter	Type	Required	Description
`containerId`	string	Yes	ID of the HTML element to render the chart in
`options`	object	No	Configuration options (see below)

Options:

Option	Type	Default	Description
`maxHeight`	number	`20`	Maximum height of the chart in rows
`maxDataPoints`	number	`30`	Maximum number of columns before old data scrolls off
`title`	string	`''`	Chart title (displayed centered at top)
`xAxisLabel`	string	`''`	X-axis label (displayed centered at bottom)
`yAxisLabel`	string	`''`	Y-axis label (displayed vertically on left side)
`autoFitWidth`	boolean	`true`	Automatically adjust font size to fit container width

Example:

const chart = new ASCIIBarChart('my-chart', {
    maxHeight: 25,
    maxDataPoints: 50,
    title: 'Server Response Times',
    xAxisLabel: 'Request Number',
    yAxisLabel: 'Milliseconds',
    autoFitWidth: true
});

Methods

`addValue(value)`

Adds a new data point to the chart.

Parameters:

value (number): The numeric value to add to the chart

Example:

chart.addValue(42);
chart.addValue(38);
chart.addValue(45);

`clear()`

Clears all data from the chart and resets it to initial state.

Example:

chart.clear();

Features in Detail

Auto-Scaling Y-Axis

The Y-axis automatically scales to show the full range of your data:

Minimum value always displays as one 'X' at the bottom
Maximum value uses the full chart height
Y-axis labels show actual data values, not just row numbers
Dynamically adjusts as new data arrives

Scrolling Data Window

When the number of data points exceeds maxDataPoints:

Old data automatically scrolls off the left side
X-axis labels update to show actual data point numbers
Maintains a sliding window of the most recent data

Responsive Font Sizing

When autoFitWidth is enabled:

Font size automatically adjusts to fill container width
Responds to window resizing in real-time
Maintains readability with min/max font size bounds (4px-20px)
Uses ResizeObserver for efficient updates

Vertical Y-Axis Label

The Y-axis label is rendered vertically, one character per row:

V
a
l
u
e

Advanced Usage

Real-Time Data Streaming

const chart = new ASCIIBarChart('chart', {
    maxHeight: 20,
    maxDataPoints: 60,
    title: 'Live Metrics'
});

// Simulate real-time data
setInterval(() => {
    const value = Math.random() * 100;
    chart.addValue(value);
}, 1000);

Integration with Data Sources

// WebSocket example
const ws = new WebSocket('ws://your-server.com/data');
ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    chart.addValue(data.value);
};

// API polling example
async function fetchAndUpdate() {
    const response = await fetch('/api/metrics');
    const data = await response.json();
    chart.addValue(data.currentValue);
}
setInterval(fetchAndUpdate, 5000);

Multiple Charts

const cpuChart = new ASCIIBarChart('cpu-chart', {
    title: 'CPU Usage %',
    yAxisLabel: 'Percent'
});

const memChart = new ASCIIBarChart('mem-chart', {
    title: 'Memory Usage MB',
    yAxisLabel: 'Megabytes'
});

// Update both charts
cpuChart.addValue(45);
memChart.addValue(2048);

Styling

The chart uses monospaced fonts and renders as plain text. Style the container element:

#chart-container {
    font-family: 'Courier New', Courier, monospace;
    background-color: #000;
    color: #0f0;
    padding: 20px;
    border: 2px solid #0f0;
    border-radius: 5px;
    white-space: pre;
    overflow-x: auto;
    font-size: 12px;
    line-height: 1.0;
}

Browser Support

Modern browsers with ES6 support
ResizeObserver API (for auto-fit width feature)
All major browsers: Chrome, Firefox, Safari, Edge

License

MIT License - feel free to use in your projects!

Examples

See text_graph.html for a complete working example with:

Interactive controls (Start/Stop/Reset)
Configurable settings (update interval, max columns, chart height)
Test data generator with increasing trend
Full styling and layout

Contributing

Contributions welcome! This is a simple, focused library for ASCII-based charting.

Changelog

v1.0.0

Initial release
Dynamic vertical bar charts
Auto-scaling Y-axis
Scrolling data window
Responsive font sizing
Customizable labels and titles