/opentui

OpenTUI Core (@opentui/core)

The foundational library for building terminal user interfaces. Provides an imperative API with all primitives, giving you maximum control over rendering, state, and behavior.

Overview

OpenTUI Core runs on Bun with native Zig bindings for performance-critical operations:

• Renderer: Manages terminal output, input events, and the rendering loop
• Renderables: Hierarchical UI building blocks with Yoga layout
• Constructs: Declarative wrappers for composing Renderables
• FrameBuffer: Low-level 2D rendering surface for custom graphics

When to Use Core

Use the core imperative API when:

• Building a library or framework on top of OpenTUI
• Need maximum control over rendering and state
• Want smallest possible bundle size (no React/Solid runtime)
• Building performance-critical applications
• Integrating with existing imperative codebases

When NOT to Use Core

Quick Start

Using create-tui (Recommended)

bunx create-tui@latest -t core my-app
cd my-app
bun run src/index.ts

The CLI creates the my-app directory for you - it must not already exist.

Agent guidance: Always use autonomous mode with -t <template> flag. Never use interactive mode (bunx create-tui@latest my-app without -t) as it requires user prompts that agents cannot respond to.

Manual Setup

mkdir my-tui && cd my-tui
bun init
bun install @opentui/core

import { createCliRenderer, TextRenderable, BoxRenderable } from "@opentui/core"

const renderer = await createCliRenderer()

// Create a box container
const container = new BoxRenderable(renderer, {
  id: "container",
  width: 40,
  height: 10,
  border: true,
  borderStyle: "rounded",
  padding: 1,
})

// Create text inside the box
const greeting = new TextRenderable(renderer, {
  id: "greeting",
  content: "Hello, OpenTUI!",
  fg: "#00FF00",
})

// Compose the tree
container.add(greeting)
renderer.root.add(container)

Core Concepts

Renderer

The CliRenderer orchestrates everything:

• Manages the terminal viewport and alternate screen
• Handles input events (keyboard, mouse, paste)
• Runs the rendering loop (configurable FPS)
• Provides the root node for the renderable tree

Renderables vs Constructs

Storage Options

Renderables can be composed in two ways:

1. Imperative: Create instances, call .add() to compose
2. Declarative (Constructs): Create VNodes, pass children as arguments

Essential Commands

bun install @opentui/core     # Install
bun run src/index.ts          # Run directly (no build needed)
bun test                      # Run tests

Runtime Requirements

OpenTUI runs on Bun (reference runtime) and uses Zig for native builds. Node.js 26.4.0 or later is also supported for the native renderer when launched with --experimental-ffi; importing core/keymap without a native renderer works on Node without FFI. See Gotchas for the full Node.js notes.

# Package management
bun install @opentui/core

# Running
bun run src/index.ts
bun test

# Building (only needed for native code changes)
bun run build

Zig is required for building native components.

Additional Capabilities

• Audio — loaded sounds, MP3/FLAC streams, input capture, and WAV recording via Audio. See API.

• Images — decode and display PNG, JPEG, WebP, and GIF content. See Text & Display.

• Clipboard — combine native host reads/writes with terminal OSC 52. See Keyboard.

• Notifications — renderer.triggerNotification(message, title?) (OSC 9/777/99). See API.

• SSH — serve a TUI over SSH with the @opentui/ssh package:

  import { createServer } from "@opentui/ssh"
  import { BoxRenderable, TextRenderable } from "@opentui/core"
  
  const server = createServer({
    hostKey: { path: "./host_key" },  // auto-generated on first run
    auth: { publicKey: "any" },
  }).serve((session) => {
    const { renderer, identity } = session   // renderer is bound to the SSH channel
    const box = new BoxRenderable(renderer, { width: "100%", height: "100%", border: true })
    box.add(new TextRenderable(renderer, { content: `Hello, ${identity.username}!` }))
    renderer.root.add(box)
  })
  
  await server.listen(2222)  // ssh -p 2222 localhost

  @opentui/core is a peer dependency; works with core, React (createRoot), and Solid (render).

In This Reference

• Configuration - Renderer options, environment variables
• API - Renderer, Renderables, types, utilities
• Patterns - Composition, events, state management
• Gotchas - Common issues, debugging, limitations

See Also

• React - React reconciler for declarative TUI
• Solid - Solid reconciler for declarative TUI
• Layout - Yoga/Flexbox layout system
• Components - Component reference by category
• Keyboard - Input handling and shortcuts
• Testing - Test renderer and snapshots