Skip to main content

Quick Start

Build your first unblessed application in 5 minutes.

Creating a Simple Dashboard​

Let's create an interactive dashboard with a list, status box, and keyboard controls.

1. Initialize Project​

mkdir my-tui-app
cd my-tui-app
pnpm init
pnpm add @unblessed/node tsx

2. Create the App​

Create index.ts:

import { Screen, Box, List } from '@unblessed/node';

// Create screen
const screen = new Screen({
  smartCSR: true,
  title: 'My Dashboard'
});

// Header
const header = new Box({
  parent: screen,
  top: 0,
  left: 0,
  width: '100%',
  height: 3,
  content: '{center}{bold}Welcome to unblessed!{/bold}{/center}',
  tags: true,
  style: {
    fg: 'white',
    bg: 'blue'
  }
});

// Sidebar menu
const menu = new List({
  parent: screen,
  top: 3,
  left: 0,
  width: '30%',
  height: '100%-6',
  label: ' Menu ',
  border: { type: 'line' },
  style: {
    border: { fg: 'cyan' },
    selected: {
      bg: 'cyan',
      fg: 'black'
    }
  },
  keys: true,
  vi: true,
  mouse: true,
  items: ['Dashboard', 'Settings', 'Help', 'Exit']
});

// Content area
const content = new Box({
  parent: screen,
  top: 3,
  left: '30%',
  width: '70%',
  height: '100%-6',
  border: { type: 'line' },
  label: ' Content ',
  tags: true,
  content: '{center}Select a menu item{/center}'
});

// Footer
const footer = new Box({
  parent: screen,
  bottom: 0,
  left: 0,
  width: '100%',
  height: 3,
  content: '{center}Press q to quit | Use arrow keys to navigate{/center}',
  tags: true,
  style: {
    fg: 'white',
    bg: 'blue'
  }
});

// Handle menu selection
menu.on('select', (item, index) => {
  if (index === 3) { // Exit
    process.exit(0);
  }

  const selected = item.getText();
  content.setContent(`{center}{bold}${selected}{/bold}{/center}\\n\\nThis is the ${selected} page.`);
  screen.render();
});

// Global key handlers
screen.key(['q', 'C-c'], () => {
  process.exit(0);
});

// Focus menu and render
menu.focus();
screen.render();

3. Run the App​

tsx index.ts

4. Interact​

  • Arrow keys or j/k: Navigate menu
  • Enter: Select menu item
  • q or Ctrl+C: Quit

Understanding the Code​

Screen Creation​

const screen = new Screen({
  smartCSR: true,  // Smart cursor save/restore
  title: 'My Dashboard'
});

The Screen is the top-level container for your TUI.

Widget Hierarchy​

Widgets attach to parents using the parent option:

const box = new Box({
  parent: screen,  // Attach to screen
  // ... other options
});

Positioning & Sizing​

Use flexible positioning:

{
  top: 'center',      // Center vertically
  left: '30%',        // 30% from left
  width: '50%',       // 50% of parent width
  height: '100%-6'    // Parent height minus 6 lines
}

Styling​

Apply colors and borders:

{
  border: { type: 'line' },
  style: {
    fg: 'white',
    bg: 'blue',
    border: { fg: 'cyan' }
  }
}

Event Handling​

Listen to events:

menu.on('select', (item, index) => {
  // Handle selection
});

screen.key(['q', 'C-c'], () => {
  process.exit(0);
});

Next Steps​