Skip to main content

Widgets

Understanding unblessed's widget system.

Overview​

Widgets are the building blocks of unblessed TUIs. They provide UI elements like boxes, lists, forms, and more, all arranged in a hierarchical tree structure.

Widget Hierarchy​

All widgets inherit from the base classes:

Node (base class)
└── Element (visual base)
    ├── Box (rectangular area)
    │   ├── List (scrollable list)
    │   ├── Form (input container)
    │   ├── Table (tabular data)
    │   └── Text (formatted text)
    ├── Input (text input)
    │   ├── Textbox (single-line)
    │   └── Textarea (multi-line)
    ├── Button (clickable button)
    ├── ProgressBar (progress indicator)
    └── ... (other widgets)

Node​

The base class for all widgets:

class Node {
  parent: Node | null;
  children: Node[];
  screen: Screen | null;

  // Hierarchy methods
  append(node: Node): void;
  prepend(node: Node): void;
  insertBefore(node: Node, ref: Node): void;
  insertAfter(node: Node, ref: Node): void;
  remove(node: Node): void;
  detach(): void;

  // Event methods
  on(event: string, listener: Function): void;
  emit(event: string, ...args: any[]): void;
}

Element​

Adds visual properties to Node:

class Element extends Node {
  // Position
  top: number | string;
  left: number | string;
  width: number | string;
  height: number | string;

  // Style
  style: Style;
  border: BorderOptions;
  padding: Padding;

  // Content
  content: string;
  tags: boolean;  // Enable tag parsing

  // Methods
  render(): void;
  setContent(text: string): void;
  focus(): void;
  hide(): void;
  show(): void;
}

Core Widgets​

Box​

The fundamental rectangular widget:

import { Box } from '@unblessed/node';

const box = new Box({
  parent: screen,
  top: 'center',
  left: 'center',
  width: '50%',
  height: '50%',
  content: 'Hello {bold}World{/bold}!',
  tags: true,
  border: { type: 'line' },
  style: {
    fg: 'white',
    bg: 'blue',
    border: { fg: 'cyan' }
  }
});

Use cases: Headers, containers, panels, status bars

List​

Interactive scrollable list:

import { List } from '@unblessed/node';

const list = new List({
  parent: screen,
  top: 0,
  left: 0,
  width: '100%',
  height: '100%',
  items: ['Item 1', 'Item 2', 'Item 3'],
  keys: true,      // Arrow key navigation
  vi: true,        // Vim bindings (j/k)
  mouse: true,     // Mouse support
  style: {
    selected: {
      bg: 'cyan',
      fg: 'black'
    }
  }
});

list.on('select', (item, index) => {
  console.log(`Selected: ${item.getText()}`);
});

Use cases: Menus, file browsers, selection lists

Table​

Tabular data display:

import { Table } from '@unblessed/node';

const table = new Table({
  parent: screen,
  top: 0,
  left: 0,
  width: '100%',
  height: '100%',
  data: [
    ['Name', 'Age', 'City'],
    ['Alice', '30', 'New York'],
    ['Bob', '25', 'London'],
    ['Carol', '35', 'Tokyo']
  ],
  border: { type: 'line' },
  style: {
    header: { fg: 'blue', bold: true },
    cell: { fg: 'white' }
  }
});

Use cases: Data tables, grids, reports

Form​

Container for input widgets:

import { Form, Textbox, Button } from '@unblessed/node';

const form = new Form({
  parent: screen,
  keys: true,
  mouse: true
});

const nameInput = new Textbox({
  parent: form,
  name: 'name',
  label: 'Name:',
  top: 0,
  left: 0,
  width: '100%',
  height: 3
});

const submitButton = new Button({
  parent: form,
  content: 'Submit',
  top: 4,
  left: 0,
  height: 3
});

form.on('submit', (data) => {
  console.log('Form data:', data);
});

submitButton.on('press', () => {
  form.submit();
});

Use cases: User input, settings, dialogs

Textbox & Textarea​

Text input widgets:

import { Textbox, Textarea } from '@unblessed/node';

// Single-line input
const textbox = new Textbox({
  parent: screen,
  label: 'Username:',
  inputOnFocus: true,
  keys: true,
  mouse: true
});

// Multi-line input
const textarea = new Textarea({
  parent: screen,
  label: 'Description:',
  inputOnFocus: true,
  keys: true,
  mouse: true
});

textbox.on('submit', (value) => {
  console.log('Entered:', value);
});

Use cases: Text input, forms, editors

Button​

Clickable button:

import { Button } from '@unblessed/node';

const button = new Button({
  parent: screen,
  content: 'Click Me',
  top: 'center',
  left: 'center',
  width: 20,
  height: 3,
  mouse: true,
  style: {
    bg: 'green',
    fg: 'white',
    focus: { bg: 'cyan' }
  }
});

button.on('press', () => {
  console.log('Button clicked!');
});

Use cases: Actions, confirmations, navigation

ProgressBar​

Progress indicator:

import { ProgressBar } from '@unblessed/node';

const progress = new ProgressBar({
  parent: screen,
  top: 'center',
  left: 'center',
  width: '50%',
  height: 3,
  filled: 0,
  style: { bar: { bg: 'cyan' } }
});

let value = 0;
const interval = setInterval(() => {
  value += 10;
  progress.setProgress(value);
  screen.render();

  if (value >= 100) {
    clearInterval(interval);
  }
}, 100);

Use cases: Loading indicators, task progress

Widget Options​

Common Options​

All widgets support these options:

interface WidgetOptions {
  // Hierarchy
  parent?: Node;
  children?: Node[];

  // Position (numbers or strings)
  top?: number | string;     // 0, '50%', 'center'
  left?: number | string;
  right?: number | string;
  bottom?: number | string;

  // Size
  width?: number | string;   // 50, '50%', 'shrink'
  height?: number | string;

  // Visual
  border?: BorderOptions;
  padding?: Padding;
  style?: Style;

  // Content
  content?: string;
  tags?: boolean;            // Enable {bold}, {red-fg}, etc.
  label?: string;

  // Behavior
  hidden?: boolean;
  clickable?: boolean;
  focusable?: boolean;
  scrollable?: boolean;
  draggable?: boolean;
  mouse?: boolean;
  keys?: boolean;
  vi?: boolean;
}

Position & Sizing​

Flexible positioning system:

// Absolute
{ top: 0, left: 0, width: 50, height: 10 }

// Percentage
{ top: '10%', left: '20%', width: '50%', height: '80%' }

// Center
{ top: 'center', left: 'center', width: 30, height: 10 }

// Mixed
{ top: 2, left: 'center', width: '50%', height: 10 }

// Calculated
{ top: 0, left: 0, right: 0, bottom: 0 }  // Fill parent
{ width: '100%-10', height: '100%-5' }    // With margin

Borders​

Various border styles:

// Line border
{ border: { type: 'line' } }

// Custom characters
{ border: {
    type: 'line',
    ch: '#',
    top: true,
    bottom: true,
    left: true,
    right: true
  }
}

// Colors
{ border: { type: 'line' },
  style: { border: { fg: 'cyan', bg: 'black' } }
}

Padding​

Space inside borders:

// Uniform
{ padding: 1 }

// Per side
{ padding: { left: 2, right: 2, top: 1, bottom: 1 } }

Styles​

Colors and attributes:

{
  style: {
    fg: 'white',           // Foreground color
    bg: 'blue',            // Background color
    bold: true,
    underline: true,
    border: {
      fg: 'cyan'
    },
    focus: {               // When focused
      bg: 'yellow',
      fg: 'black'
    },
    selected: {            // For lists
      bg: 'green'
    }
  }
}

Colors: Named colors ('red', 'blue', etc.), RGB ('#ff0000'), or terminal codes.

Content Tags​

Enable rich content formatting with tags: true:

const box = new Box({
  parent: screen,
  content: '{bold}Bold text{/bold}\n' +
           '{red-fg}Red text{/red-fg}\n' +
           '{blue-bg}Blue background{/blue-bg}\n' +
           '{center}Centered{/center}',
  tags: true
});

Available tags:

  • Style: {bold}, {underline}, {blink}, {inverse}
  • Colors: {red-fg}, {blue-bg}, {#ff0000-fg}
  • Alignment: {left}, {center}, {right}
  • Reset: {/bold}, {/red-fg}, {/}

Creating Custom Widgets​

Extend existing widgets to create custom ones:

import { Box, type BoxOptions } from '@unblessed/node';

export interface StatusBoxOptions extends BoxOptions {
  status?: 'success' | 'error' | 'warning';
}

export class StatusBox extends Box {
  constructor(options: StatusBoxOptions = {}) {
    super(options);
    this.type = 'statusbox';

    // Set colors based on status
    if (options.status) {
      this.setStatus(options.status);
    }
  }

  setStatus(status: 'success' | 'error' | 'warning') {
    const colors = {
      success: { fg: 'green', border: 'green' },
      error: { fg: 'red', border: 'red' },
      warning: { fg: 'yellow', border: 'yellow' }
    };

    const color = colors[status];
    this.style.fg = color.fg;
    if (this.border) {
      this.style.border = { fg: color.border };
    }
  }
}

// Usage
const status = new StatusBox({
  parent: screen,
  status: 'success',
  content: 'Operation completed successfully!',
  border: { type: 'line' }
});

See Custom Widgets for advanced examples.

Widget Lifecycle​

Understanding widget lifecycle helps with proper resource management:

  1. Construction: Widget options processed
  2. Attachment: Added to parent, assigned screen
  3. Rendering: Visual output generated
  4. Events: User interactions handled
  5. Updates: Content/style changes
  6. Detachment: Removed from parent
  7. Destruction: Resources cleaned up
const box = new Box({ /* options */ });  // 1. Construction
box.attach(parent);                       // 2. Attachment
screen.render();                          // 3. Rendering
box.on('click', handler);                 // 4. Events
box.setContent('new content');            // 5. Updates
box.detach();                             // 6. Detachment
box.destroy();                            // 7. Destruction

Best Practices​

Use Parent Option​

// ✅ Recommended
const box = new Box({ parent: screen });

// ❌ Avoid
const box = new Box();
screen.append(box);

Batch Updates​

// ✅ Efficient
box.setContent('Line 1');
box.style.fg = 'cyan';
screen.render();  // Single render

// ❌ Inefficient
box.setContent('Line 1');
screen.render();
box.style.fg = 'cyan';
screen.render();

Clean Up Resources​

// Remove event listeners
box.removeAllListeners();

// Detach from tree
box.detach();

// Destroy widget
box.destroy();

Next Steps​