blessed-components - v1.20.0
    Preparing search index...

    blessed-components - v1.20.0

    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.

    • 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.
    npm install blessed blessed-components

    blessed is a peer dependency.

    Create a starter app:

    npx blessed-components create my-terminal-app
    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
    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
    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
    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
    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
    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
    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.

    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.

    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.

    Core hardening foundations include:

    • density-aware theme spacing, border, active-variant, high-contrast, and component tokens consumed by Blessed adapters;
    • deterministic simulated capability scenarios for Unicode/ASCII, color/no-color, mouse, and dumb-terminal behavior;
    • component color resolution that falls back from component overrides to semantic theme tokens;
    • renderer benchmarks for tables, logs, charts, and high-frequency output.

    The capability scenarios are deterministic unit-level coverage. Native macOS/Windows runners, memory/process leak checks, and enforced performance budgets remain hardening work rather than completed platform certification.

    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.

    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 benchmark
    npm run docs:index
    npm run package:generate
    npm run package: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.

    Run the component gallery:

    npm run example:gallery

    Use arrow keys or j/k and Enter to select stories, r to reload, Tab to move focus, and q to quit. The workbench presents all component stories through their public Blessed adapters with category context and live metadata.

    Run the composed application examples:

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

    Verify every example without an interactive terminal:

    npm run examples:smoke

    Generate the navigable component maturity index:

    npm run docs:index

    Benchmark render-heavy pure components after a build:

    npm run benchmark

    Regenerate package exports and build entries from source layout:

    npm run package:generate

    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.

    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.

    See library policies for stability, deprecation, fallback, performance, and packaging rules.

    MIT

    Settings

    Member Visibility

    On This Page

    blessed-components