blessed-components

Composable, typed terminal UI components for Blessed.

Project status: early development. Alert, Badge, Box, Button, Card, Dialog, Divider, EmptyState, ErrorState, Heading, Kbd, KeyValue, Label, List, MetricBars, MutedText, ProgressBar, ProgressList, ProgressStack, ScrollArea, Sparkline, Spinner, Stack, Stat, Status, MenuBar, NavigationList, Pager, Pagination, StepIndicator, TaskProgress, Text, Trend, Viewport, DateInput, TimeInput, PromptDialog, Tooltip, ToastViewport, Countdown, Schedule, CodeViewer, DiffViewer, StackTrace, EnvironmentTable, ShortcutRecorder, EventLog, CommandOutput, TerminalPane, QrCode, SplitPane, Skeleton, VirtualTable, BarChart, LineChart, Heatmap, ContextMenu, Carousel, FilePicker, Popover, TestResults, BuildStatus, GitStatus, CommitList, DependencyTree, AspectRatio, Resizable, Pill, Rating, NotificationCenter, TreeTable, ProcessList, HexViewer, AnsiViewer, StackedBarChart, AreaChart, ScatterPlot, BoxPlot, Donut, CandlestickChart, WaterfallChart, RequestInspector, QueryResults, PerformancePanel, ProcessRunner, ProcessTable, TaskRunner, REPL, ShellHistory, MarkdownViewer, RichText, Image, BigText, Calendar, DateRangePicker, and Gantt are available.

Goals

• Small, consistent component APIs.
• Deterministic renderers that can be tested without a terminal.
• Thin adapters for Blessed elements and lifecycle.
• Responsive layouts for narrow terminals.
• Unicode, ASCII, color, and no-color modes.
• TypeScript types included with every release.

Installation

npm install blessed blessed-components

blessed is a peer dependency.

Coming soon

Core components

| Component | Purpose | Priority | | ------------- | ---------------------------------------------------- | -------- | | ProgressBar | Render one bounded horizontal progress bar. | Available | | Sparkline | Render compact time-series data with Unicode blocks. | Available | | MetricBars | Render labeled metrics as aligned progress bars. | Available | | Stat | Display a label, value, trend, and description. | Available | | KeyValue | Display aligned label/value metadata. | Available | | List | Navigate and select typed items with bounded rendering. | Available | | Text | Render safe, cell-aware terminal text. | Available |

Composition

| Component | Purpose | Priority | | ---------- | ----------------------------------------------------- | -------- | | Box | Create a typed, themed container. | Available | | Card | Compose a framed header, body, and footer. | Available | | KeyValue | Display aligned label/value rows. | Available | | Badge | Display compact semantic status text. | Available | | Divider | Separate content horizontally or vertically. | Available | | Stack | Arrange children with direction, gap, and alignment. | Available | | AspectRatio | Preserve terminal-cell proportions. | Available | | Resizable | Clamp and render one resizable region. | Available | | SplitPane | Render horizontal or vertical region allocation. | Available | | ScrollArea | Scroll vertical content with keyboard and mouse. | Available | | Viewport | Clip and translate larger two-dimensional content. | Available |

Feedback and live data

| Component | Purpose | Priority | | ----------- | -------------------------------------------------- | -------- | | Spinner | Show ongoing work with controlled animation. | Available | | ProgressList | Display multiple labeled progress rows. | Available | | ProgressStack | Display segmented progress across categories. | Available | | Skeleton | Display loading placeholder rows. | Available | | NotificationCenter | Display persistent notifications and unread state. | Available | | Status | Display semantic state and optional details. | Available | | Alert | Display informational, warning, or error messages. | Available | | EmptyState | Display an empty result message with optional action. | Available | | ErrorState | Display error details, cause, and retry text. | Available | | Heading | Display hierarchical terminal heading styles. | Available | | Kbd | Display keyboard shortcuts consistently. | Available | | Label | Display stable labels for controls and values. | Available | | MutedText | Display secondary information using semantic theme tokens. | Available | | StepIndicator | Display completed, active, and pending steps. | Available | | TaskProgress | Display multi-step task status with current activity. | Available | | Trend | Display up, down, and flat indicators with text fallback. | Available | | Pill | Display compact capped labels. | Available | | Rating | Display discrete scores with numeric fallback. | Available | | LogViewer | Stream and retain bounded log output. | Available | | Timer | Display elapsed or remaining time. | Available |

Data visualization

| Component | Purpose | Priority | | ----------- | ------------------------------------- | -------- | | Table | Display structured tabular data. | Available | | TreeTable | Display hierarchical rows plus columns. | Available | | ProcessList | Display PID, CPU, memory, status, and command. | Available | | HexViewer | Display byte offsets, hex, and ASCII text. | Available | | AnsiViewer | Safely display ANSI-formatted output. | Available | | VirtualTable | Render a bounded row window from large tables. | Available | | BarChart | Compare categorical values. | Available | | StackedBarChart | Compare category composition. | Available | | LineChart | Display one or more sampled time series. | Available | | AreaChart | Display a filled sampled trend. | Available | | ScatterPlot | Display x/y relationships. | Available | | BoxPlot | Display statistical summaries. | Available | | Donut | Display part-to-whole summaries. | Available | | CandlestickChart | Display OHLC rows. | Available | | WaterfallChart | Display sequential contributions. | Available | | Histogram | Display value distributions. | Available | | Tree | Navigate hierarchical data. | Available | | Heatmap | Display dense two-dimensional values. | Available |

Interaction

| Component | Purpose | Priority | | ---------------- | ---------------------------- | -------- | | Button | Trigger a focusable terminal action. | Available | | IconButton | Compact action with required text description. | Available | | NumberField | Numeric input with parsing, bounds, and step. | Available | | PasswordField | Masked input with reveal behavior. | Available | | DateInput | Parse and validate date text. | Available | | TimeInput | Parse and validate time text. | Available | | Tabs | Switch between views. | Available | | Menu | Navigate a list of actions. | Available | | MenuBar | Navigate top-level horizontal menus. | Available | | NavigationList | Navigate routes or views with active state. | Available | | Pager | Move to previous or next page. | Available | | Pagination | Move through bounded result pages. | Available | | ContextMenu | Render anchored action choices. | Available | | Carousel | Render one active slide with position metadata. | Available | | FilePicker | Render caller-provided filesystem entries. | Available | | Select | Choose one or more values. | Available | | TextField | Enter and validate text. | Available | | Form | Compose terminal inputs. | Available | | CommandPalette | Search and execute commands. | Available |

Overlays

| Component | Purpose | Priority | | --- | --- | --- | | Dialog | Show modal content with trapped and restored focus. | Available | | Drawer | Show edge-attached temporary content. | Available | | Spotlight | Search and launch actions or resources. | Available | | PromptDialog | Request one value in a modal flow. | Available | | Popover | Show anchored temporary content. | Available | | Tooltip | Show delayed contextual help. | Available |

Developer tools

| Component | Purpose | Priority | | --- | --- | --- | | CodeViewer | Render source with line numbers. | Available | | DiffViewer | Render unified diff rows. | Available | | StackTrace | Render structured stack frames. | Available | | EnvironmentTable | Render masked environment variables. | Available | | ShortcutRecorder | Display captured terminal shortcuts. | Available | | EventLog | Render structured TUI events. | Available | | CommandOutput | Render read-only command output. | Available | | TestResults | Render test outcomes, durations, and failures. | Available | | BuildStatus | Render build phases and outcome. | Available | | GitStatus | Render branch and changed file groups. | Available | | CommitList | Render commit summaries and refs. | Available | | DependencyTree | Render dependency hierarchy and problems. | Available | | RequestInspector | Render HTTP request and response details. | Available | | QueryResults | Render database rows and execution metadata. | Available | | PerformancePanel | Render runtime performance counters. | Available | | TerminalPane | Display a scrollable terminal session pane. | Available | | ProcessRunner | Render command execution state. | Available | | ProcessTable | Render multiple managed process states. | Available | | TaskRunner | Render named task state. | Available | | REPL | Render prompt, history, and input. | Available | | ShellHistory | Render searchable command history. | Available |

Date, time, and content

| Component | Purpose | Priority | | --- | --- | --- | | Countdown | Display remaining time until completion. | Available | | Calendar | Navigate and select dates. | Available | | DateRangePicker | Display a bounded date interval. | Available | | Gantt | Display time-based task spans. | Available | | Schedule | Display ordered upcoming events. | Available | | QrCode | Render a supplied QR/module matrix. | Available | | MarkdownViewer | Render Markdown as terminal-safe text. | Available | | RichText | Render styled spans as plain text. | Available | | Image | Render image fallback text with alt. | Available | | BigText | Render large-text fallback. | Available | | ToastViewport | Position and manage toast notifications. | Available |

See ROADMAP.md for milestones, proposed APIs, and TDD strategy.

Architecture

src/
  core/         framework-independent rendering primitives
  primitives/   headless interaction and state machines
  components/   categorized pure component renderers
  adapters/     Blessed widget adapters
tests/
  public-api/           behavior through exported APIs
  blessed-integration/  integration with real Blessed elements
examples/
  component-gallery/    interactive stories for every component
  dashboard/            composed service-dashboard template
  process-monitor/      live system metrics and lifecycle example

Renderers remain independent from Blessed. Adapters own element updates, listeners, timers, and cleanup.

Current component source categories include collections, content, data-display, developer-tools, feedback, input, layout, overlays, scheduling, and visualization. Public npm subpaths remain component-oriented, for example blessed-components/list and blessed-components/dialog.

Core utilities

The framework-independent core provides terminal-aware text measurement, truncation, wrapping, cropping, numeric scaling, series sampling, formatting, capability detection, character sets, themes, events, focus, keymaps, layout, and render models.

Import the complete core:

import { formatBytes, truncateText, visibleWidth } from 'blessed-components/core';

Or use focused, tree-shakable subpaths:

import { sampleSeries } from 'blessed-components/core/scale';
import { visibleWidth } from 'blessed-components/core/width';

See the core reference.

Headless primitives

Primitives compose core algorithms into reusable behavior without choosing presentation or creating Blessed elements:

• Collection provides stable ordered identity and enabled-item navigation.
• Selection provides single and multiple selection state.
• FocusScope captures, traps, and restores focus identifiers.
• Viewport provides bounded two-dimensional offsets and visibility.
• ScrollArea provides line, page, and scrollbar behavior.
• Overlay provides layer ordering, modal blocking, Escape dismissal, and focus-return metadata.

import { createSelectionModel } from 'blessed-components/primitives/selection';

const selection = createSelectionModel({
  items: [
    { id: 'one' },
    { id: 'two' },
  ],
});

selection.select('two');

See the primitives reference.

Development

Requires Node.js 22.14 or newer.

npm install
npm run validate

Useful commands:

npm run build
npm run docs
npm run docs:check
npm test
npm run test:watch
npm run lint
npm run lint:fix
npm run biome:check
npm run preview
npm run typecheck
npm run format
npm run format:check

ESLint and Biome extend the shared super-configs presets. Biome owns formatting and import organization; Prettier is not used.

Terminal component preview

Run the component gallery:

npm run example:gallery

Use arrow keys and Enter to select stories, r to reload, Tab to move focus, and q to quit. The prototype previews Badge, MetricBars, ProgressBar, available component stories through their public Blessed adapters.

Run the composed application examples:

npm run example:dashboard
npm run example:process-monitor

Verify every example without an interactive terminal:

npm run examples:smoke

Testing

Development follows vertical TDD slices:

1. Add one failing test for public behavior.
2. Add minimum implementation needed to pass.
3. Refactor while tests remain green.
4. Repeat with next behavior.

Tests should use public interfaces and observable output. Internal mocks and large snapshots are avoided.

Releases and documentation

semantic-release publishes packages from main. After a real npm release succeeds, the same workflow generates TypeDoc for the released version and deploys docs/api to GitHub Pages. Commits that produce no release do not deploy documentation.

Each release also updates CHANGELOG.md and commits the generated changelog and package version with a [skip ci] release commit.

License

MIT