Opentui

• CLI tools with rich interfaces
• Terminal-based games
• Developer tools (terminal editors, debuggers)
• System monitoring applications
• Interactive command-line applications

2. Installation and Setup

Prerequisites

• Bun 1.3.0+ (recommended) or Node.js 18+
• Zig 0.15.2 (required only for building from source)

Quick Start with create-tui

bun create tui my-app
cd my-app
bun run src/index.ts

Select a template (React, Solid, or vanilla TypeScript) during creation.

Manual Installation

# Core package only
bun add @opentui/core

# With React
bun add @opentui/react @opentui/core react

# With Solid
bun add @opentui-ui/solid @opentui/core solid-js

TypeScript Configuration

For React projects using OpenTUI:

{
  "compilerOptions": {
    "lib": ["ESNext", "DOM"],
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "jsxImportSource": "@opentui/react",
    "strict": true,
    "skipLibCheck": true
  }
}

3. Core Concepts and Architecture

Renderer

The CliRenderer is the core of OpenTUI. It manages terminal output, handles input events, runs the rendering loop, and provides context for creating renderables.

import { createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer({
  exitOnCtrlC: true,
  targetFps: 30,
})

Screen Modes

• alternate-screen (default): Full-screen TUI application
• main-screen: Render without switching buffers
• split-footer: Pin renderer to footer region

Renderables vs Constructs

OpenTUI provides two APIs:

1. Renderable API: Object-oriented, imperative style

   const box = new BoxRenderable(renderer, { width: 30, height: 10 })
   box.add(text)
   renderer.root.add(box)
   

2. Construct API: Declarative, functional style

   renderer.root.add(
     Box({ width: 30, height: 10 }, Text({ content: "Hello" }))
   )
   

Layout System

OpenTUI uses the Yoga layout engine with CSS Flexbox-like properties:

Box({
  flexDirection: "row",
  justifyContent: "space-between",
  alignItems: "center",
  width: "100%",
  height: 10,
  padding: 2,
  gap: 1,
})

Keyboard Input

renderer.keyInput.on("keypress", (key) => {
  if (key.name === "escape") {
    renderer.destroy()
    process.exit(0)
  }
})

Colors

import { RGBA } from "@opentui/core"

const red = RGBA.fromHex("#FF0000")
const blue = RGBA.fromInts(0, 0, 255, 255)

// Or use string colors directly
Text({ content: "Hello", fg: "#00FFFF" })
Box({ backgroundColor: "blue" })

Lifecycle

Always call renderer.destroy() on exit to restore terminal state:

process.on("uncaughtException", () => {
  renderer.destroy()
  process.exit(1)
})

4. API Reference

Core Functions

Core Components

React Hooks

Events

Common events emitted by components:

• change: Value changed
• input: Input event
• submit: Form submit
• itemSelected: Item selected in list
• focus: Component focused
• blur: Component lost focus

5. Practical Examples

Hello World

import { createCliRenderer, Text } from "@opentui/core"

const renderer = await createCliRenderer()
renderer.root.add(Text({ content: "Hello, OpenTUI!", fg: "#00FFFF" }))

Interactive Counter

import { createCliRenderer, Box, Text } from "@opentui/core"

const renderer = await createCliRenderer()
let count = 0

const display = Text({ content: "Count: 0", fg: "#FFFF00" })

renderer.keyInput.on("keypress", (key) => {
  if (key.name === "up") {
    count++
    display.setContent(`Count: ${count}`)
    renderer.requestRender()
  } else if (key.name === "down") {
    count--
    display.setContent(`Count: ${count}`)
    renderer.requestRender()
  }
})

renderer.root.add(display)

Login Form

import { createCliRenderer } from "@opentui/core"
import { createRoot } from "@opentui/react"

function LoginForm() {
  return (
    <box style={{ border: true, padding: 2, flexDirection: "column", gap: 1 }}>
      <text fg="#FFFF00">Login</text>
      <box title="Username" style={{ border: true, width: 30, height: 3 }}>
        <input placeholder="Username..." />
      </box>
      <box title="Password" style={{ border: true, width: 30, height: 3 }}>
        <input placeholder="Password..." />
      </box>
    </box>
  )
}

const renderer = await createCliRenderer()
createRoot(renderer).render(<LoginForm />)

File Menu

import { createCliRenderer, Box, Select } from "@opentui/core"

const renderer = await createCliRenderer()

const menu = Select({
  width: 25,
  height: 10,
  options: [
    { name: "New File", description: "Create new (Ctrl+N)" },
    { name: "Open...", description: "Open file (Ctrl+O)" },
    { name: "Save", description: "Save (Ctrl+S)" },
    { name: "Exit", description: "Quit (Ctrl+Q)" },
  ],
})

menu.on("itemSelected", (index, option) => {
  console.log("Selected:", option.name)
})

menu.focus()
renderer.root.add(Box({ border: true, borderStyle: "rounded" }, menu))

Flexbox Layout

renderer.root.add(
  Box({
    flexDirection: "row",
    width: "100%",
    height: "100%",
    padding: 1,
  },
    Box({
      flexGrow: 1,
      border: true,
      borderStyle: "rounded",
    }, Text({ content: "Left Panel" })),
    Box({
      width: 30,
      border: true,
      borderStyle: "rounded",
    }, Text({ content: "Right" })),
  )
)

6. Configuration and Customization

Renderer Options

const renderer = await createCliRenderer({
  screenMode: "alternate-screen",
  exitOnCtrlC: true,
  targetFps: 30,
  maxFps: 60,
  useMouse: true,
  autoFocus: true,
  backgroundColor: "#000000",
})

Styling Components

Box({
  width: 40,
  height: 15,
  backgroundColor: "#1a1a1a",
  border: true,
  borderStyle: "rounded",
  borderColor: "#666666",
  padding: 2,
  margin: 1,
})

Border Styles

• single: Single line (┌─┐│└─┘)
• double: Double line (╔═╗║╚═╝)
• rounded: Rounded corners (╭─╮│╰─╯)
• heavy: Heavy lines (┏━┓┃┗━┛)

Theme Mode Detection

const mode = renderer.themeMode
renderer.on("theme_mode", (newMode) => {
  console.log("Theme changed to:", newMode)
})

7. Troubleshooting

Common Issues

Terminal stays broken after crash:

• Run reset command in terminal
• Add error handlers calling renderer.destroy()

Mouse not working:

• Ensure useMouse: true in config
• Check terminal supports mouse protocol

Input not receiving keys:

• Call input.focus() on the component
• Check no other component has focus

Environment Variables

Debug Overlay

renderer.toggleDebugOverlay()

renderer.configureDebugOverlay({
  enabled: true,
  corner: "topRight",
})

8. Best Practices

Performance

• Use requestRender() instead of continuous rendering when possible
• Batch DOM updates in React by using state
• Use renderable.requestRender() for targeted updates

Accessibility

• Always provide focus indicators
• Use clear, high-contrast colors
• Support keyboard navigation for all interactive elements

Clean Shutdown

const renderer = await createCliRenderer()

process.on("uncaughtException", () => {
  renderer.destroy()
  process.exit(1)
})

process.on("unhandledRejection", () => {
  renderer.destroy()
  process.exit(1)
})

Component Structure

function Panel({ title, children }) {
  return (
    <box
      style={{
        border: true,
        borderStyle: "rounded",
        padding: 1,
        margin: 1,
      }}
    >
      <text bold fg="#00FFFF">{title}</text>
      {children}
    </box>
  )
}

9. Integration

React Integration

import { createCliRenderer } from "@opentui/core"
import { createRoot } from "@opentui/react"

function App() {
  return <box><text>Hello React!</text></box>
}

const renderer = await createCliRenderer()
createRoot(renderer).render(<App />)

SolidJS Integration

import { createCliRenderer } from "@opentui/core"
import { createRoot as createSolidRoot } from "@opentui-ui/solid"

function App() {
  return <box><text>Hello Solid!</text></box>
}

const renderer = await createCliRenderer()
createSolidRoot(renderer).render(<App />)

Tree-sitter for Syntax Highlighting

OpenTUI supports tree-sitter for code syntax highlighting. Set the worker path:

OTUI_TREE_SITTER_WORKER_PATH=/path/to/worker.js

10. Advanced Features

Custom Renderables

import { BoxRenderable, type RenderContext, type BoxOptions } from "@opentui/core"

class CustomButton extends BoxRenderable {
  constructor(ctx: RenderContext, options: BoxOptions & { label?: string }) {
    super(ctx, options)
    this.borderStyle = "rounded"
    this.padding = 2
  }
}

Animations with useTimeline

import { useTimeline } from "@opentui/react"
import { useEffect, useState } from "react"

function AnimatedBox() {
  const [width, setWidth] = useState(0)
  const timeline = useTimeline({ duration: 2000, loop: true })

  useEffect(() => {
    timeline.add(
      { width },
      {
        width: 50,
        duration: 2000,
        ease: "linear",
        onUpdate: (anim) => setWidth(anim.targets[0].width),
      }
    )
  }, [])

  return <box style={{ width, backgroundColor: "#6a5acd" }} />
}

Cursor Control

renderer.setCursorPosition(10, 5, true)
renderer.setCursorStyle({ style: "block", blinking: true })

Memory Management

renderer.on("memory:snapshot", (snapshot) => {
  console.log("Memory:", snapshot)
})

References

For detailed API documentation, see:

• references/api-quickref.md - Quick API reference
• references/examples.md - Extended code examples