Skip to content

Display Widgets

Display widgets in @termuijs/widgets cover text visualization, AI output patterns, and decorative typography.

StreamingText

Renders text character by character with a typewriter effect. When NO_MOTION=1, the full text is shown immediately.

·CODE
import { StreamingText } from '@termuijs/widgets'

const widget = new StreamingText(
    {
        text: 'Generating response...',
        speed: 30,                           // characters per second
        cursor: '▋',                         // blinking cursor (ASCII: '_')
        onComplete: () => console.log('done'),
    },
    { flexGrow: 1 }
)
OptionTypeDefaultDescription
textstringRequiredText to stream
speednumber40Characters per second
cursorstring'▋' / '_'Cursor character. Defaults to unicode block or ASCII underscore based on caps.unicode
onComplete() => void-Called when all characters have been rendered

ChatMessage

A chat bubble with role-aware styling. Different roles get different colors and alignment:

·CODE
import { ChatMessage } from '@termuijs/widgets'

const userMsg = new ChatMessage(
    { role: 'user', content: 'How do I sort an array in TypeScript?' },
    { flexGrow: 1 }
)

const assistantMsg = new ChatMessage(
    { role: 'assistant', content: 'Use `.sort()` with a comparator function...' },
    { flexGrow: 1 }
)
OptionTypeDescription
role`'user' \'assistant' \
contentstringMessage text (supports newlines)
timestampstringOptional timestamp shown in dim text below the message

Role styling defaults:

  • user, right-aligned, blue border
  • assistant, left-aligned, green border
  • system, centered, dimmed, gray border

ToolCall

Displays an AI tool/function call with status indicator and collapsible details:

·CODE
import { ToolCall } from '@termuijs/widgets'

const widget = new ToolCall(
    {
        name: 'readFile',
        status: 'running',
        args: { path: '/etc/hosts' },
    },
    { flexGrow: 1 }
)

// Update status as the call progresses
widget.setStatus('done')
widget.setResult('127.0.0.1  localhost\n::1        localhost\n')
OptionTypeDescription
namestringFunction/tool name
status`'pending' \'running' \
argsRecord<string, unknown>Arguments, shown in a collapsible section
resultunknownReturn value, shown after status is 'done'

JSONView

A collapsible, navigable tree for displaying JSON data:

·CODE
import { JSONView } from '@termuijs/widgets'

const widget = new JSONView(
    {
        data: { name: 'Alice', scores: [98, 87, 92], active: true },
        indent: 2,
        onSelect: (path, value) => console.log(path, value),
    },
    { flexGrow: 1 }
)

Users can expand/collapse objects and arrays with Enter. onSelect fires when a node is focused.

OptionTypeDescription
dataunknownAny JSON-serializable value
indentnumberSpaces per indent level (default: 2)
onSelect(path: string[], value: unknown) => voidFires when a node is selected

DiffView

Renders a unified diff with colored + / - lines:

·CODE
import { DiffView } from '@termuijs/widgets'
import type { DiffLine } from '@termuijs/widgets'

const lines: DiffLine[] = [
    { type: 'context', content: '  function greet(name: string) {' },
    { type: 'remove',  content: '    return "Hello " + name' },
    { type: 'add',     content: '    return `Hello, ${name}!`' },
    { type: 'context', content: '  }' },
]

const widget = new DiffView({ lines }, { flexGrow: 1 })

Or pass a raw unified diff string, use the diffView() quick builder which parses it automatically:

·CODE
import { diffView } from '@termuijs/quick'

const w = diffView('+ added line\n- removed line\n  unchanged')

BigText

Large ASCII art banner text using a built-in 5×3 character map. No external dependencies:

·CODE
import { BigText } from '@termuijs/widgets'

const banner = new BigText('HELLO', { flexGrow: 1 }, {
    color: { type: 'named', name: 'cyan' },
})

Supports uppercase A–Z, digits 0–9, and common punctuation. Unsupported characters are skipped.

OptionTypeDescription
colorColorColor of the rendered characters

Gradient

Renders text with a smooth color gradient applied per character. Uses ANSI 256-color interpolation:

·CODE
import { Gradient } from '@termuijs/widgets'

const header = new Gradient('Terminal Dashboard',
    { flexGrow: 1 },
    { startColor: '#ff6b6b', endColor: '#4ecdc4', align: 'center' }
)
OptionTypeDefaultDescription
startColorstring'#ff0000'Hex color at the start of the text
endColorstring'#0000ff'Hex color at the end of the text
align`'left' \'center' \'right'`

Gradient degrades gracefully in terminals without 256-color support, it falls back to the nearest available color.

Markdown

Renders a Markdown string as formatted terminal output with bold, italic, inline code, and block-level elements.

PropTypeDescription
contentstringMarkdown source to render
widthnumberMaximum line width for wrapping
·CODE
import { Markdown } from '@termuijs/widgets'

const widget = new Markdown({ flexGrow: 1 }, { content: '# Hello\n\nThis is **bold** text.' })

Code

Displays a fenced code block with optional syntax label and line numbers.

PropTypeDescription
sourcestringCode text to display
languagestringLanguage label shown in the header
lineNumbersbooleanShow line numbers on the left
·CODE
import { Code } from '@termuijs/widgets'

const widget = new Code({ flexGrow: 1 }, {
    source: 'const x = 1',
    language: 'typescript',
    lineNumbers: true,
})

Highlight

Renders a string with specific substrings highlighted in a contrasting color, for search-result emphasis.

PropTypeDescription
textstringFull text to display
querystringSubstring to highlight
colorColorColor applied to matched ranges
·CODE
import { Highlight } from '@termuijs/widgets'

const widget = new Highlight({ flexGrow: 1 }, { text: 'Hello world', query: 'world' })

Typewriter

Streams text character by character with a configurable delay. Respects NO_MOTION, shows the full string immediately when motion is disabled.

PropTypeDescription
textstringText to animate
delayMsnumberMilliseconds per character
onComplete() => voidCalled when animation finishes
·CODE
import { Typewriter } from '@termuijs/widgets'

const widget = new Typewriter({ flexGrow: 1 }, { text: 'Loading...', delayMs: 40 })

Digits

Renders a number as large ASCII art digits. Useful for clocks and counters.

PropTypeDescription
valuestring | numberValue to render
colorColorColor of the digit segments
·CODE
import { Digits } from '@termuijs/widgets'

const widget = new Digits({ height: 5 }, { value: '12:34', color: { type: 'named', name: 'cyan' } })

Marquee

Scrolls text horizontally in a loop. Respects NO_MOTION, shows the text static when motion is disabled.

PropTypeDescription
textstringText to scroll
speednumberColumns per second
·CODE
import { Marquee } from '@termuijs/widgets'

const widget = new Marquee({ height: 1, flexGrow: 1 }, { text: 'Breaking news: TermUI v0.1.6 released', speed: 8 })

Callout

A bordered block for drawing attention to a note, warning, or tip.

PropTypeDescription
messagestringText inside the callout
variant'info' | 'warning' | 'error' | 'tip'Sets the icon and border color
·CODE
import { Callout } from '@termuijs/widgets'

const widget = new Callout({ flexGrow: 1 }, { message: 'Run with --debug for verbose output.', variant: 'tip' })

Kbd

Renders a keyboard key in a bordered box, like ⌘K or Ctrl+S.

PropTypeDescription
keysstring[]Key labels to render
·CODE
import { Kbd } from '@termuijs/widgets'

const widget = new Kbd({}, { keys: ['Ctrl', 'S'] })

Hexdump

Displays raw binary data as a hex dump with offset, hex bytes, and ASCII columns.

PropTypeDescription
dataUint8Array | BufferBinary data to display
bytesPerRownumberBytes per row (default: 16)
·CODE
import { Hexdump } from '@termuijs/widgets'

const widget = new Hexdump({ flexGrow: 1 }, { data: Buffer.from('Hello, TermUI!') })

Stat

Shows a single metric with a label and optional delta indicator.

PropTypeDescription
labelstringMetric name
valuestring | numberCurrent value
deltastringOptional change string, e.g. '+12%'
·CODE
import { Stat } from '@termuijs/widgets'

const widget = new Stat({}, { label: 'Requests', value: '4,821', delta: '+8%' })

Avatar

Renders a user avatar as initials or a small pixel art block in the terminal.

PropTypeDescription
namestringName used to derive initials
colorColorBackground color
·CODE
import { Avatar } from '@termuijs/widgets'

const widget = new Avatar({}, { name: 'Alice B', color: { type: 'named', name: 'blue' } })

Badge

A compact inline label with a colored background, for status tags or counts.

PropTypeDescription
labelstringText inside the badge
colorColorBackground color
·CODE
import { Badge } from '@termuijs/widgets'

const widget = new Badge({}, { label: 'NEW', color: { type: 'named', name: 'green' } })

Tag

A bordered inline label, similar to Badge but uses a border instead of a filled background.

PropTypeDescription
labelstringText inside the tag
colorColorBorder and text color
·CODE
import { Tag } from '@termuijs/widgets'

const widget = new Tag({}, { label: 'v0.1.6', color: { type: 'named', name: 'cyan' } })

EmptyState

A centered placeholder shown when a list or view has no content.

PropTypeDescription
messagestringPrimary message
hintstringSecondary hint text
·CODE
import { EmptyState } from '@termuijs/widgets'

const widget = new EmptyState({ flexGrow: 1 }, { message: 'No results found', hint: 'Try a different search term.' })

Placeholder

A fixed-size box with a label, used as a layout placeholder during development.

PropTypeDescription
labelstringText shown inside the box
·CODE
import { Placeholder } from '@termuijs/widgets'

const widget = new Placeholder({ width: 20, height: 5 }, { label: 'Chart goes here' })

Watermark

Renders a faint watermark text centered in its container.

PropTypeDescription
textstringWatermark text
·CODE
import { Watermark } from '@termuijs/widgets'

const widget = new Watermark({ flexGrow: 1 }, { text: 'DRAFT' })

See also