https://github.com/pppp606/ink-chart
Terminal visualization components for Ink CLI framework - Sparkline and BarChart components with TypeScript support
https://github.com/pppp606/ink-chart
barchart chart cli ink nodejs react sparkline terminal typescript visualization
Last synced: 4 months ago
JSON representation
Terminal visualization components for Ink CLI framework - Sparkline and BarChart components with TypeScript support
- Host: GitHub
- URL: https://github.com/pppp606/ink-chart
- Owner: pppp606
- License: mit
- Created: 2025-08-29T01:44:24.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-01-21T04:10:29.000Z (5 months ago)
- Last Synced: 2026-01-21T16:53:10.987Z (5 months ago)
- Topics: barchart, chart, cli, ink, nodejs, react, sparkline, terminal, typescript, visualization
- Language: TypeScript
- Size: 1.91 MB
- Stars: 10
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# ink-chart
Terminal visualization components for [Ink](https://github.com/vadimdemedes/ink), React CLI framework
## Preview
## Features
- **BarChart** - Horizontal bar charts with individual row coloring and custom formatting
- **StackedBarChart** - 100% stacked horizontal bar charts showing percentage distribution
- **LineGraph** - High-resolution line graphs with multi-series support and axis labels
- **Sparkline** - Compact trend visualization with threshold highlighting and gradient colors
- **TypeScript** - Full TypeScript support with comprehensive type definitions
- **Auto-width** - Responsive charts that adapt to terminal width
- **Gradient Colors** - 8-level smooth color gradients with automatic terminal compatibility
- **Performance** - Optimized rendering with React.memo to prevent flickering
## Installation
```bash
npm install @pppp606/ink-chart
```
## Quick Start
```tsx
import React from 'react';
import { render, Text, Box } from 'ink';
import { BarChart, StackedBarChart, LineGraph, Sparkline } from '@pppp606/ink-chart';
function App() {
return (
{/* Bar chart with values */}
{/* Stacked bar chart showing distribution */}
{/* Line graph with multiple series */}
{/* Simple sparkline */}
);
}
render();
```
## Components
### BarChart
Horizontal bar charts with customizable appearance and individual row colors.
```tsx
`${v}%`}
/>
```
Output:
```
Success ████████████████████████████████████████████████████████████████████ 22%
Errors ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 15%
Warnings ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ 8%
```
**Props:**
- `data: BarChartData[]` - Array of data points
- `sort?: 'none' | 'asc' | 'desc'` - Sort order
- `showValue?: 'right' | 'inside' | 'none'` - Value display position
- `width?: 'auto' | 'full' | number` - Chart width (`'auto'`: natural content width, `'full'`: terminal width, `number`: fixed width)
- `max?: 'auto' | number` - Maximum value for scaling
- `format?: (value: number) => string` - Value formatter
- `barChar?: '▆' | '█' | '▓' | '▒' | '░'` - Bar character
- `color?: string` - Default color (overridden by individual `BarChartData.color`)
**BarChartData interface:**
```tsx
interface BarChartData {
label: string;
value: number;
color?: string; // Hex code or Ink color name
}
```
### StackedBarChart
Stacked horizontal bar chart with two modes: 100% percentage distribution or absolute values.
```tsx
```
Output:
```
Sales Warning Error
███████████████▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
30.0% 20.0% 50.0%
```
**Props:**
- `data: StackedBarSegment[]` - Array of segments to display
- `mode?: 'percentage' | 'absolute'` - Display mode (default: `'percentage'`)
- `'percentage'`: 100% stacked showing percentage distribution
- `'absolute'`: Stacked bar showing actual values scaled to max
- `max?: 'auto' | number` - Maximum value for scaling in absolute mode (default: `'auto'`)
- `width?: 'auto' | 'full' | number` - Chart width (`'auto'`: 40 characters default, `'full'`: terminal width, `number`: fixed width)
- `showLabels?: boolean` - Whether to show segment labels above bar (default: `true`)
- `showValues?: boolean` - Whether to show values below bar (default: `true`)
- `format?: (value: number, mode: StackedBarChartMode) => string` - Value formatter
**StackedBarSegment interface:**
```tsx
interface StackedBarSegment {
label: string;
value: number;
color?: string; // Hex code or Ink color name
char?: string; // Custom character for this segment
}
```
### LineGraph
High-resolution line graph using Unicode scan line characters (⎺ ⎻ ─ ⎼ ⎽) for 5-level vertical resolution per row.
```tsx
```
Output:
```
140│ ⎽─⎺
│ ⎽─⎺⎻─⎻
│ ⎽⎼─⎺
│ ⎽─⎺⎻─⎻
│⎽⎼─⎺
100│⎺
└──────────────────────
Q1 Q4
```
**Props:**
- `data: LineGraphSeries[]` - Array of data series (each with `values` and optional `color`)
- `width?: 'auto' | 'full' | number` - Chart width
- `height?: number` - Chart height in rows (default: 10, each row = 5 vertical levels)
- `yDomain?: 'auto' | [number, number]` - Y-axis range
- `showYAxis?: boolean` - Show Y-axis labels (default: false)
- `yLabels?: (string | number)[]` - Custom Y-axis labels (numbers: position-based, strings: evenly distributed)
- `xLabels?: (string | number)[]` - X-axis labels (numbers: position-based, strings: evenly distributed)
- `caption?: string` - Optional caption below chart
**LineGraphSeries interface:**
```tsx
interface LineGraphSeries {
values: number[];
color?: string; // Ink color name or hex
}
```
### Sparkline
Compact trend visualization perfect for displaying time series data.
```tsx
```
Output:
```
▂▄▃█▅
Sales Trend
```
**Props:**
- `data: number[]` - Array of numeric values
- `width?: 'auto' | 'full' | number` - Chart width (`'auto'`: data length, `'full'`: terminal width, `number`: fixed width)
- `threshold?: number | number[]` - Threshold(s) for highlighting (single or gradient)
- `colorScheme?: 'red' | 'blue' | 'green'` - Color scheme for gradient highlighting
- `mode?: 'block' | 'braille'` - Rendering mode
- `caption?: string` - Optional caption below chart
## Advanced Features
### Smooth Color Gradients
8-level gradient highlighting with automatic terminal compatibility:
```tsx
```
**Color Support:**
- **24-bit terminals** (iTerm, VSCode): Full RGB gradients
- **256-color terminals**: Palette-based gradients
- **16-color terminals**: Basic color fallbacks
Detection is automatic based on `COLORTERM`, `TERM`, and `TERM_PROGRAM` environment variables.
### Performance Optimization
Components are optimized with `React.memo` to prevent unnecessary re-renders:
```tsx
// Only re-renders when values actually change
```
### Full-width Support
Charts can adapt to full terminal width:
```tsx
// Full terminal width
// Full terminal width
```
## Security
This package implements comprehensive security practices:
- **Secure CI/CD**: SHA-pinned GitHub Actions with minimal permissions
- **Supply Chain Protection**: Provenance attestation and OIDC authentication
- **Secret Scanning**: Automated detection of accidentally committed secrets
- **Dependency Security**: Regular security audits and automated vulnerability scanning
- **Workflow Protection**: CODEOWNERS file and branch protection rules
For security policy, vulnerability reporting, and detailed security information, see [SECURITY.md](SECURITY.md).
## License
MIT