@oxog/tui

Build beautiful terminal interfaces with TypeScript - A zero-dependency, micro-kernel TUI framework for Node.js

Features

• 🚀 Zero External Dependencies - Only uses @oxog/* packages
• 🔌 Micro-kernel Architecture - Modular plugin system for extensibility
• 📦 TypeScript-First - Full type safety and excellent IntelliSense
• ⚡ Differential Rendering - Optimal performance with minimal redraws
• 🎨 Flexbox-like Layout - Familiar layout system without external dependencies
• 🧩 50+ Built-in Widgets - Everything you need to build terminal UIs
• 🎭 10+ Built-in Themes - Beautiful themes including dark, light, and high contrast
• ⌨️ Full Input Handling - Comprehensive keyboard and mouse support
• 🔄 Animation Support - Tweening and frame-based animations
• ♿ Accessible - High contrast theme and keyboard navigation support

Installation

npm install @oxog/tui

Quick Start

import { tui, box, text } from '@oxog/tui'
import { standardPlugins } from '@oxog/tui/plugins'

// Create the application
const app = tui({
  plugins: standardPlugins(),
  title: 'My TUI App'
})

// Build the UI
const root = box({ flexDirection: 'column' })
  .justify('center')
  .align('center')
  .add(text('Hello, World!').fg('#00ff00').bold(true))

// Handle keyboard input
app.on('key', (event) => {
  if (event.key === 'q') app.quit()
})

// Mount and start
app.mount(root)
app.start()

Terminal Output

┌─────────────────────────────────────────────────────────┐
│                                                         │
│                     Hello, World!                       │
│                                                         │
│                     Press q to quit                       │
│                                                         │
└─────────────────────────────────────────────────────────┘

Widgets

@oxog/tui includes 50+ built-in widgets:

Layout Containers

• Box - Flexible container with padding, margin, border
• Grid - CSS Grid-like 2D layout
• SplitPane - Resizable split panels
• Tabs - Tabbed navigation
• Accordion - Collapsible panels

Form Widgets

• Input - Text input field
• Textarea - Multi-line text editor
• Select - Dropdown selection list
• Checkbox - Toggle checkbox
• Slider - Range slider
• Form - Form with validation

Data Display

• Text - Styled text display
• Table - Data table with sorting
• Tree - Hierarchical tree view
• List - Virtual scroll list
• DataGrid - Advanced table with filtering

Feedback Widgets

• Progress - Progress bar
• Spinner - Loading animation
• Toast - Notification messages
• Modal - Dialog windows
• Statusbar - Status information
• Badge/Tag - Small status indicators
• Tooltip - Hover tooltips

Advanced Widgets

• Calendar - Date picker
• ColorPicker - Color selection
• CommandPalette - Quick command launcher
• ContextMenu - Right-click menus
• Menubar - Application menu bar
• Breadcrumb - Navigation breadcrumb
• Wizard - Multi-step wizard
• Pagination - Data pagination
• SearchInput - Search with suggestions

Content Widgets

• CodeViewer - Syntax highlighted code
• MarkdownViewer - Markdown rendering
• LogViewer - Log file viewer
• JsonViewer - JSON pretty printer
• Image - ASCII art image display
• Terminal - Embedded terminal
• DiffViewer - Side-by-side diff

Visualization Widgets

• BarChart - Bar chart
• Sparkline - Mini chart
• Gauge - Gauge/meter
• Heatmap - Heat map visualization
• Timeline - Timeline view
• Kanban - Kanban board
• Stopwatch - Timer/stopwatch

Plugins

Extend functionality with plugins:

import { standardPlugins } from '@oxog/tui/plugins'

const app = tui({
  plugins: [
    ...standardPlugins(), // Core plugins
    animationPlugin(),  // Animations
    mousePlugin(),      // Mouse support
    clipboardPlugin()   // Copy/paste
  ]
})

Available Plugins

Plugin	Description
rendererPlugin	Differential rendering to terminal
layoutPlugin	Flexbox-like layout engine
stylePlugin	Theme and style resolution
inputPlugin	Keyboard input handling
mousePlugin	Mouse event handling
focusPlugin	Focus management
animationPlugin	Animation and tweening
scrollPlugin	Scrollable content
clipboardPlugin	Copy/paste support
screenPlugin	Screen management
statePlugin	Redux-like state management
shortcutsPlugin	Keyboard shortcuts
responsivePlugin	Responsive layouts
routerPlugin	URL-like routing

Theming

Built-in themes:

import {
  defaultTheme,
  lightTheme,
  draculaTheme,
  nordTheme,
  monokaiTheme,
  gruvboxTheme,
  solarizedDarkTheme,
  tokyoNightTheme,
  catppuccinMochaTheme,
  highContrastTheme
} from '@oxog/tui'

Create custom themes:

import { createTheme, defaultTheme } from '@oxog/tui'

const myTheme = createTheme('my', defaultTheme, {
  colors: {
    primary: '#ff0066',
    background: '#1a1a2e'
  }
})

Layout System

Flexbox-like layout:

box()
  .direction('row')           // Main axis
  .justify('center')         // Main alignment
  .align('stretch')          // Cross alignment
  .gap(1)                    // Spacing
  .padding(2)                // Padding
  .width(50)                 // Fixed width
  .height('50%')             // Percentage height
  .flex(1)                   // Grow factor

Documentation

• Architecture - System architecture and design
• Plugin Development - Creating custom plugins
• Performance Guide - Optimization techniques
• Accessibility Guide - Building accessible UIs
• Contributing - Contribution guidelines

Examples

See the examples directory for complete examples:

• 01-hello-world.ts - Basic setup
• 02-box-layout.ts - Flexbox layout
• 03-form.ts - Form inputs
• 04-progress-spinner.ts - Progress and spinner
• 05-table.ts - Data table
• 06-tree.ts - Tree view
• 07-tabs.ts - Tabbed interface
• 08-textarea.ts - Text editor
• 09-theming.ts - Theme switching
• comprehensive-dashboard.ts - Full-featured dashboard
• app-system-monitor.ts - System monitor app
• app-music-player.ts - Music player app
• app-git-client.ts - Git client app

# Run examples
npm run example:hello
npm run example:dashboard

API Reference

Quick API

Export	Description
tui(options)	Create TUI application
box(props)	Box container widget
text(content)	Text display widget
input(props)	Input field widget
select(props)	Select dropdown widget
checkbox(props)	Checkbox widget
progress(props)	Progress bar widget
spinner(props)	Loading spinner widget
textarea(props)	Textarea widget
table(props)	Data table widget
tree(props)	Tree view widget
tabs(props)	Tabs widget
modal(props)	Modal dialog widget
toast	Toast notifications
standardPlugins()	Get standard plugins

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT © Ersin Koç

---

Made with ❤️ by Ersin Koç

Website • Documentation • GitHub • npm