# uPlot — Fast Small Time Series Chart Library

> A tiny, wickedly fast time series charting library that renders millions of data points smoothly using Canvas, designed for dashboards and monitoring where performance matters most.

## Install

Save in your project root:

# uPlot — Fast Small Time Series Chart Library

## Quick Use
```bash
npm install uplot
# In your app:
# import uPlot from 'uplot';
# import 'uplot/dist/uPlot.min.css';
# const data = [ [1621900000, 1621910000], [42, 58] ];
# const opts = { width: 800, height: 400, series: [{}, { stroke: 'red' }] };
# new uPlot(opts, data, document.getElementById('chart'));
```

## Introduction
uPlot is a fast, memory-efficient Canvas-based charting library built specifically for time series data. It can render millions of data points without jank, making it ideal for monitoring dashboards, IoT panels, and any application where performance with large datasets is critical.

## What uPlot Does
- Renders time series line, area, bar, and scatter charts on HTML5 Canvas
- Handles millions of data points with sub-millisecond draw times
- Provides interactive zoom, pan, and cursor tracking with crosshair tooltips
- Supports multiple Y axes, dual scales, and series toggling
- Allows plugin-based extensions for custom overlays and behaviors

## Architecture Overview
uPlot operates on columnar typed arrays where the first column is timestamps and subsequent columns are series values. The renderer uses Canvas 2D for drawing, applying path simplification and viewport clipping to skip off-screen points. Scales and axes are computed lazily, and the cursor system uses binary search for fast data point lookup. The result is a library that stays under 50 KB while outperforming most SVG-based alternatives by orders of magnitude.

## Self-Hosting & Configuration
- Install from npm and import alongside its minimal CSS stylesheet
- Pass options (width, height, series config) and columnar data to the constructor
- Configure scales, axes, and grid lines through the options object
- Enable zoom with `scales: { x: { range: [min, max] } }` and mouse drag handlers
- Use hooks like `drawAxes`, `drawSeries`, and `setCursor` for custom behavior

## Key Features
- Renders 10 million points in under 100 ms on typical hardware
- Under 50 KB minified with no runtime dependencies
- Columnar data format minimizes memory overhead and GC pressure
- Built-in zoom, pan, and linked cursor across multiple chart instances
- Plugin hooks for adding annotations, thresholds, and custom drawing

## Comparison with Similar Tools
- **Chart.js** — Higher-level API with many chart types; uPlot is faster for large time series
- **D3.js** — Low-level SVG toolkit; uPlot is a ready-made Canvas chart with better performance at scale
- **Grafana Panels** — Dashboard framework; uPlot is the actual rendering engine used inside Grafana
- **Frappe Charts** — SVG-based with a friendly API; uPlot trades API simplicity for raw speed on large data

## FAQ
**Q: Why columnar data instead of row objects?**
A: Columnar typed arrays are cache-friendly and reduce memory allocations, which is critical for rendering millions of points.

**Q: Can uPlot render non-time-series data?**
A: Yes. While optimized for time series, any numeric X axis works. Set `scales: { x: { time: false } }` for general data.

**Q: Does it support real-time streaming data?**
A: Yes. Append new points to the data arrays and call `uPlot.setData()` to update the chart efficiently.

**Q: Is uPlot used in production systems?**
A: Yes. Grafana uses uPlot as its primary time series rendering engine for dashboards.

## Sources
- https://github.com/leeoniya/uPlot
- https://leeoniya.github.io/uPlot/demos

---
Source: https://tokrepo.com/en/workflows/asset-8c1ce706
Author: AI Open Source