# ASCII Bar Chart
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:
```html
```
## Quick Start
```html
```
## API Reference
### Constructor
```javascript
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:**
```javascript
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:**
```javascript
chart.addValue(42);
chart.addValue(38);
chart.addValue(45);
```
#### `clear()`
Clears all data from the chart and resets it to initial state.
**Example:**
```javascript
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
```javascript
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
```javascript
// 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
```javascript
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:
```css
#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`](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