JSPM

@termuijs/widgets

0.1.3
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 79
  • Score
    100M100P100Q75758F
  • License MIT

Box, Text, Table, ProgressBar, Spinner, Gauge, VirtualList, and more for TermUI

Package Exports

  • @termuijs/widgets

Readme

@termuijs/widgets

The building blocks for terminal UIs. Boxes, text, tables, progress bars, spinners, gauges, and a virtualized list that handles millions of rows without breaking a sweat.

Install

npm install @termuijs/widgets

Requires @termuijs/core as a peer dependency.

Widgets

Widget What it is
Box Container with flexbox layout, borders, padding, margin
Text Styled text. Color, bold, italic, underline, strikethrough, dim
Table Data table with headers, column alignment, row selection
ProgressBar Horizontal bar with percentage fill and optional label
Spinner Animated loading indicator. Ships with multiple animation styles
Gauge Arc or circular gauge for numeric values
TextInput Single-line text input with cursor, placeholder, and change callback
List Scrollable list with keyboard selection. Good for small datasets
VirtualList Scroll-virtualized list. Renders only the visible rows, so 1M items costs the same as 10
LogView Tailing log viewer with auto-scroll and configurable buffer limit
Sparkline Inline line chart from an array of numbers
StatusIndicator Colored dot with a label (ok / warn / error / unknown)
BarChart Horizontal or vertical bar chart with grouping
Scrollbar Standalone scrollbar indicator

Usage

import { Box, Text, ProgressBar, VirtualList } from '@termuijs/widgets'

const container = new Box({
    flexDirection: 'column',
    border: 'rounded',
    padding: 1,
})

container.addChild(new Text({ content: 'Downloads', bold: true }))
container.addChild(new ProgressBar({ value: 0.73, width: 30 }))

// VirtualList renders only visible rows
const list = new VirtualList({
    totalItems: 100_000,
    renderItem: (i) => `Row ${i}`,
    onSelect: (i) => console.log('picked', i),
})
container.addChild(list)

VirtualList

The standout addition. It only paints the items that fit in the viewport, plus a small overscan buffer above and below. A list of 100,000 items renders the same ~26 rows as a list of 10.

const list = new VirtualList({
    totalItems: data.length,
    itemHeight: 1,
    overscan: 2,
    renderItem: (index) => `${data[index].name}${data[index].status}`,
    onSelect: (index) => inspect(data[index]),
})

// Navigation
list.selectNext()
list.selectPrev()
list.pageDown()
list.selectFirst()
list.selectLast()
list.scrollTo(500)
list.confirm()        // fires onSelect with current index

// Update data on the fly
list.setTotalItems(newData.length)
list.setRenderItem((i) => newData[i].label)

Every widget supports

  • visible — show or hide
  • focusable — whether Tab stops on this widget
  • style — colors, borders, padding, margin
  • markDirty() — flags the widget for re-render on the next frame
  • Focus ring rendering when focused

Documentation

Full docs at www.termui.io/docs/widgets/overview.

License

MIT