Opentui

OpenTUI Core Development

Expert assistance for building terminal user interfaces with OpenTUI's imperative API.

Quick Start

# Install dependencies
bun install @opentui/core

# Zig is required for native modules
# Install from: https://ziglang.org/download/

Core Components

Basic Pattern

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

async function main() {
  const renderer = await createCliRenderer()

  const box = new BoxRenderable()
  const text = new TextRenderable("Hello, OpenTUI!")
  box.add(text)

  renderer.getRoot().add(box)
  renderer.start()

  // Handle Ctrl+C to exit
  renderer.on("key", (key) => {
    if (key.name === "c" && key.ctrl) {
      renderer.destroy()
      process.exit(0)
    }
  })
}

main()

Layout with Yoga (CSS Flexbox)

import { Yoga } from "@opentui/core"

const group = new GroupRenderable()
group.setStyle({
  flexDirection: "column",
  justifyContent: "center",
  alignItems: "center",
  width: 80,
  height: 24,
})

See LAYOUT.md for all Yoga properties.

Input Handling

Keyboard Events

renderer.on("key", (key: KeyEvent) => {
  if (key.name === "escape") process.exit(0)
  if (key.name === "c" && key.ctrl) process.exit(0)
})

Component Input Events

const input = new InputRenderable()
input.on("submit", (value: string) => {
  console.log("Submitted:", value)
})
input.on("change", (value: string) => {
  console.log("Changed:", value)
})

See INPUT.md for complete event handling patterns.

Styling & Colors

import { Color, parseColor } from "@opentui/core"

// Create colors
const red = new Color(255, 0, 0)        // RGB integers
const blue = Color.fromInts(0, 0, 255) // Static method
const green = parseColor("#00FF00")     // Parse hex

// Apply styles
box.setStyle({
  backgroundColor: red,
  foregroundColor: blue,
  borderStyle: "double",
  paddingLeft: 2,
  paddingRight: 2,
})

See STYLING.md for color system and style properties.

Animations

import { Timeline } from "@opentui/core"

const box = new BoxRenderable()
const timeline = new Timeline({
  duration: 1000,
  easing: (t) => t * (2 - t), // easeOutQuad
})

timeline.to(box, {
  backgroundColor: new Color(255, 0, 0),
}, {
  onUpdate: () => renderer.render()
})

timeline.play()

See ANIMATION.md for animation patterns.

Debugging

// Enable console overlay
import { consoleOverlay } from "@opentui/core"
renderer.attach(consoleOverlay())

// Now console.log() appears in terminal overlay
console.log("Debug: initialized")

When to Use This Skill

Use /opentui for:

• Building TUIs with vanilla TypeScript/JavaScript
• Creating custom OpenTUI components
• Understanding core OpenTUI architecture
• Performance optimization
• Low-level debugging

For React-specific development, use /opentui-react For SolidJS-specific development, use /opentui-solid For project scaffolding and examples, use /opentui-projects

Common Tasks

• Create a form: Use BoxRenderable + InputRenderable components with Yoga layout
• Handle keyboard shortcuts: Listen to renderer "key" events
• Make scrollable lists: Use ScrollBoxRenderable with dynamic content
• Display code: Use CodeRenderable for syntax highlighting
• Add borders: Use BoxRenderable with borderStyle property

Resources

• Component API - Complete component reference
• Layout Guide - Yoga flexbox properties
• Event Handling - Keyboard, mouse, clipboard
• Styling - Colors, borders, spacing
• Animations - Timeline and easing
• Testing - Testing utilities

Key Knowledge Sources

• OpenTUI GitHub: https://github.com/sst/opentui
• Context7: /sst/opentui (168 code snippets, High reputation)
• Research: .search-data/research/opentui/

OpenTUI Animations

Timeline Animation System

OpenTUI uses a Timeline-based animation system for smooth, performant animations.

Basic Animation

import { Timeline } from "@opentui/core"

const box = new BoxRenderable()

const timeline = new Timeline({
  duration: 1000,        // ms
  easing: (t) => t,      // linear
  loop: false,           // don't repeat
  autoplay: false,       // don't start automatically
})

timeline.to(box, {
  backgroundColor: new Color(255, 0, 0),
}, {
  onUpdate: () => renderer.render(),
})

timeline.play()

Easing Functions

// Built-in easing functions
const easings = {
  linear: (t: number) => t,

  // Quad
  easeInQuad: (t: number) => t * t,
  easeOutQuad: (t: number) => t * (2 - t),
  easeInOutQuad: (t: number) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t,

  // Cubic
  easeInCubic: (t: number) => t * t * t,
  easeOutCubic: (t: number) => (--t) * t * t + 1,
  easeInOutCubic: (t: number) => t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1,

  // Quart
  easeInQuart: (t: number) => t * t * t * t,
  easeOutQuart: (t: number) => 1 - (--t) * t * t * t,
  easeInOutQuart: (t: number) => t < 0.5 ? 8 * t * t * t * t : 1 - 8 * (--t) * t * t * t,

  // Quint
  easeInQuint: (t: number) => t * t * t * t * t,
  easeOutQuint: (t: number) => 1 + (--t) * t * t * t * t,
  easeInOutQuint: (t: number) => t < 0.5 ? 16 * t * t * t * t * t : 1 + 16 * (--t) * t * t * t * t,
}

// Usage
const timeline = new Timeline({
  duration: 500,
  easing: easings.easeOutQuad,
})

Animation Properties

Animatable Properties

// Color interpolation
timeline.to(box, {
  backgroundColor: new Color(255, 0, 0),
  foregroundColor: new Color(0, 0, 255),
})

// Number interpolation (for custom properties)
timeline.to(box, {
  customProperty: 100,
}, {
  onUpdate: (progress) => {
    // Use progress value
    box.setStyle({ width: progress })
  }
})

Animation Sequences

Sequential Animations

const timeline = new Timeline()

// First animation
timeline.to(box, { backgroundColor: new Color(255, 0, 0) }, { duration: 500 })

// Second animation (after first completes)
timeline.to(box, { backgroundColor: new Color(0, 255, 0) }, { duration: 500 })

// Third animation
timeline.to(box, { backgroundColor: new Color(0, 0, 255) }, { duration: 500 })

timeline.play()

Parallel Animations

const box1 = new BoxRenderable()
const box2 = new BoxRenderable()

const timeline1 = new Timeline()
timeline1.to(box1, { backgroundColor: new Color(255, 0, 0) }, { duration: 1000 })

const timeline2 = new Timeline()
timeline2.to(box2, { backgroundColor: new Color(0, 255, 0) }, { duration: 1000 })

timeline1.play()
timeline2.play()

Animation Control

const timeline = new Timeline({ duration: 1000 })

// Start animation
timeline.play()

// Pause animation
timeline.pause()

// Resume from pause
timeline.resume()

// Stop and reset
timeline.stop()

// Reverse animation
timeline.reverse()

// Seek to specific time
timeline.seek(500) // 500ms

// Get current progress (0-1)
console.log(timeline.getProgress())

// Get current time (ms)
console.log(timeline.getTime())

Looping

Infinite Loop

const timeline = new Timeline({
  duration: 1000,
  loop: true,
  easing: easings.easeInOutQuad,
})

timeline.to(box, {
  backgroundColor: new Color(255, 0, 0),
}, {
  yoyo: true, // Oscillate back and forth
})

Counted Loop

let loopCount = 0
const maxLoops = 3

const timeline = new Timeline({
  duration: 1000,
  loop: true,
})

timeline.to(box, {
  backgroundColor: new Color(255, 0, 0),
}, {
  onComplete: () => {
    loopCount++
    if (loopCount >= maxLoops) {
      timeline.stop()
    }
  }
})

Animation Events

const timeline = new Timeline({ duration: 1000 })

timeline.to(box, {
  backgroundColor: new Color(255, 0, 0),
}, {
  onUpdate: (progress) => {
    console.log("Progress:", progress)
    renderer.render()
  },

  onComplete: () => {
    console.log("Animation complete!")
  },

  onStart: () => {
    console.log("Animation started!")
  }
})

Animation Engine

Attaching to Renderer

import { AnimationEngine } from "@opentui/core"

const animationEngine = new AnimationEngine()
renderer.attach(animationEngine)

const timeline = new Timeline({ duration: 1000 })
animationEngine.register(timeline)

Multiple Timelines

const engine = new AnimationEngine()

const timeline1 = new Timeline({ duration: 500 })
const timeline2 = new Timeline({ duration: 1000 })
const timeline3 = new Timeline({ duration: 750 })

engine.register(timeline1)
engine.register(timeline2)
engine.register(timeline3)

engine.start() // Start all timelines

Common Animation Patterns

Fade In

function fadeIn(component: any, duration: number = 500) {
  const timeline = new Timeline({ duration })

  timeline.to(component, {
    opacity: 1,
  }, {
    from: { opacity: 0 },
    onUpdate: () => renderer.render(),
  })

  return timeline
}

Slide In

function slideIn(component: any, from: "left" | "right" | "top" | "bottom", duration: number = 500) {
  const timeline = new Timeline({ duration, easing: easings.easeOutQuad })

  const startPositions = {
    left: { left: -100 },
    right: { left: 100 },
    top: { top: -20 },
    bottom: { top: 20 },
  }

  timeline.to(component, {
    left: 0,
    top: 0,
  }, {
    from: startPositions[from],
    onUpdate: () => renderer.render(),
  })

  return timeline
}

Pulse Effect

function pulse(component: any, duration: number = 1000) {
  const timeline = new Timeline({
    duration,
    loop: true,
    easing: easings.easeInOutQuad,
  })

  const originalColor = component.getStyle().foregroundColor

  timeline.to(component, {
    foregroundColor: new Color(255, 255, 255),
  }, {
    yoyo: true,
    from: { foregroundColor: originalColor },
    onUpdate: () => renderer.render(),
  })

  return timeline
}

Progress Bar

class ProgressBar {
  private box: BoxRenderable
  private fill: BoxRenderable
  private timeline: Timeline

  constructor() {
    this.box = new BoxRenderable()
    this.box.setStyle({ width: 50, height: 3 })

    this.fill = new BoxRenderable()
    this.fill.setStyle({
      width: 0,
      height: 1,
      backgroundColor: new Color(46, 204, 113),
    })

    this.box.add(this.fill)
  }

  animate(progress: number, duration: number = 500) {
    this.timeline = new Timeline({ duration, easing: easings.easeOutQuad })

    this.timeline.to(this.fill, {
      width: progress,
    }, {
      onUpdate: () => renderer.render(),
    })

    this.timeline.play()
  }
}

Performance Tips

1. Use requestAnimationFrame: OpenTUI handles this via AnimationEngine 2. Avoid too many concurrent animations: Keep it under 10-15 3. Use simple easing: Complex easing functions add overhead 4. Optimize onUpdate: Only render when necessary 5. Clean up: Stop timelines when components are destroyed

Reference

• Timeline API: OpenTUI core types
• AnimationEngine: OpenTUI core types
• Examples: .search-data/research/opentui/resources.md

OpenTUI Component Reference

TextRenderable

Display text with styling options.

import { TextRenderable } from "@opentui/core"

const text = new TextRenderable("Hello, World!")
text.setStyle({
  foregroundColor: new Color(255, 255, 255),
  textDecoration: "bold",
})

// Update text
text.setText("New text")

// Multiline text
const multiline = new TextRenderable("Line 1\nLine 2\nLine 3")

Props/Options:

• text: string - Initial text content
• wrap: boolean - Enable text wrapping
• truncate: "start" | "end" | "middle" - Truncation mode

Methods:

• setText(text: string) - Update text content
• getText(): string - Get current text

Events:

• None

---

BoxRenderable

Container with borders and backgrounds.

import { BoxRenderable } from "@opentui/core"

const box = new BoxRenderable()
box.setStyle({
  borderStyle: "single",
  borderColor: new Color(255, 255, 255),
  backgroundColor: new Color(30, 30, 30),
  padding: 1,
})

// Add children
const text = new TextRenderable("Content")
box.add(text)

Style Properties:

• borderStyle: "single" | "double" | "round" | "bold" | "dashed" | "none"
• borderColor: Color
• backgroundColor: Color
• foregroundColor: Color
• paddingTop, paddingBottom, paddingLeft, paddingRight: number
• padding: number - Shorthand

Methods:

• add(child: Renderable) - Add child component
• remove(child: Renderable) - Remove child component
• clear() - Remove all children

Events:

• click - Mouse click
• mouseover - Mouse enters
• mouseout - Mouse leaves

---

GroupRenderable

Layout container using Yoga flexbox.

import { GroupRenderable } from "@opentui/core"

const group = new GroupRenderable()
group.setStyle({
  flexDirection: "row",
  justifyContent: "space-between",
  alignItems: "center",
  gap: 2,
})

Style Properties: All Yoga layout properties (see LAYOUT.md):

• flexDirection: "row" | "column" | "row-reverse" | "column-reverse"
• justifyContent: "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | "space-evenly"
• alignItems: "flex-start" | "center" | "flex-end" | "stretch"
• alignContent: "flex-start" | "center" | "flex-end" | "stretch" | "space-between" | "space-around"
• flexWrap: "nowrap" | "wrap" | "wrap-reverse"
• gap, rowGap, columnGap: number
• Child: flexGrow, flexShrink, flexBasis: number
• Child: alignSelf: "auto" | "flex-start" | "center" | "flex-end" | "stretch"
• Child: width, height, minWidth, minHeight, maxWidth, maxHeight: number
• Child: position: "relative" | "absolute"
• Child: top, left, right, bottom: number

Methods:

• add(child: Renderable) - Add child
• remove(child: Renderable) - Remove child
• clear() - Remove all children

---

InputRenderable

Single-line text input field.

import { InputRenderable } from "@opentui/core"

const input = new InputRenderable()
input.setStyle({
  backgroundColor: new Color(50, 50, 50),
  foregroundColor: new Color(255, 255, 255),
  borderStyle: "single",
})

// Set placeholder
input.setPlaceholder("Enter text...")

// Set initial value
input.setValue("Initial value")

// Focus
input.focus()

Style Properties:

• backgroundColor: Color
• foregroundColor: Color
• borderStyle, borderColor: string | Color
• placeholderColor: Color - Placeholder text color
• cursorColor: Color - Cursor color

Methods:

• setValue(value: string) - Set input value
• getValue(): string - Get current value
• setPlaceholder(text: string) - Set placeholder
• focus() - Focus input
• blur() - Remove focus
• isFocused(): boolean - Check focus state
• clear() - Clear value

Events:

• change(value: string) - Value changed
• submit(value: string) - Enter pressed
• focus() - Input focused
• blur() - Input blurred

---

SelectRenderable

Dropdown selection component.

import { SelectRenderable } from "@opentui/core"

const select = new SelectRenderable({
  options: [
    { label: "Option 1", value: "1" },
    { label: "Option 2", value: "2" },
    { label: "Option 3", value: "3" },
  ],
})

// Get selected value
console.log(select.getValue())

// Set selected value
select.setValue("2")

Options:

• options: Array<{ label: string, value: string }> - Available options

Methods:

• setValue(value: string) - Set selected value
• getValue(): string - Get current value
• setOptions(options: Array<{ label: string, value: string }>) - Update options
• focus() - Focus select
• blur() - Remove focus

Events:

• change(value: string) - Selection changed
• submit(value: string) - Option selected
• focus() - Select focused
• blur() - Select blurred

---

ScrollBoxRenderable

Scrollable content container.

import { ScrollBoxRenderable } from "@opentui/core"

const scrollBox = new ScrollBoxRenderable()
scrollBox.setStyle({
  width: 60,
  height: 20,
})

// Add content
for (let i = 0; i < 100; i++) {
  const text = new TextRenderable(`Line ${i}`)
  scrollBox.add(text)
}

// Scroll to position
scrollBox.scrollTo(50)

// Get scroll position
console.log(scrollBox.getScrollOffset())

Style Properties:

• width, height: number - Dimensions
• backgroundColor, foregroundColor: Color
• borderStyle, borderColor: string | Color

Methods:

• scrollTo(offset: number) - Scroll to offset
• scrollBy(delta: number) - Scroll by amount
• getScrollOffset(): number - Get current offset
• getMaxScroll(): number - Get maximum scroll offset
• add(child: Renderable) - Add child
• clear() - Remove all children

Events:

• scroll(offset: number) - Scroll position changed

---

CodeRenderable

Syntax-highlighted code display.

import { CodeRenderable } from "@opentui/core"

const code = new CodeRenderable()
code.setCode(`
function hello() {
  console.log("Hello, World!");
}
`, "javascript")

// Set language
code.setLanguage("typescript")

// Get code
console.log(code.getCode())

Supported Languages:

• javascript, typescript
• python, rust, go
• json, yaml, xml
• html, css
• bash, shell
• And more...

Methods:

• setCode(code: string, language?: string) - Set code and language
• getCode(): string - Get current code
• setLanguage(language: string) - Change language
• getLanguage(): string - Get current language

---

Component Lifecycle

const component = new BoxRenderable()

// Created
console.log("Component created")

// Mounted (added to parent)
parent.add(component)
console.log("Component mounted")

// Updated
component.setStyle({ backgroundColor: new Color(255, 0, 0) })
console.log("Component updated")

// Destroyed
parent.remove(component)
console.log("Component destroyed")

Component Utilities

Find by Type

function findByType<T>(parent: any, type: new (...args: any[]) => T): T | null {
  // Implementation depends on OpenTUI internals
  return null
}

Traverse Children

function traverse(component: any, callback: (child: any) => void) {
  // Implementation depends on OpenTUI internals
}

Reference

• Component API: OpenTUI core source code
• Examples: .search-data/research/opentui/resources.md

OpenTUI Input Handling

Keyboard Events

Renderer-Level Keyboard Handling

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

const renderer = await createCliRenderer()

renderer.on("key", (key: KeyEvent) => {
  // Basic key info
  console.log(key.name)     // 'a', 'enter', 'escape', etc.
  console.log(key.sequence) // Raw character sequence
  console.log(key.ctrl)     // boolean
  console.log(key.meta)     // boolean (Command on Mac)
  console.log(key.shift)    // boolean

  // Common patterns
  if (key.name === "c" && key.ctrl) {
    // Ctrl+C
    process.exit(0)
  }

  if (key.name === "escape") {
    // ESC key
    process.exit(0)
  }

  if (key.name === "q") {
    // Quit on 'q'
    renderer.destroy()
  }
})

Special Keys

Modifier Combinations

// Ctrl+Key combinations
if (key.ctrl && key.name === "s") { /* Save */ }
if (key.ctrl && key.name === "c") { /* Copy */ }
if (key.ctrl && key.name === "v") { /* Paste */ }
if (key.ctrl && key.name === "z") { /* Undo */ }

// Shift+Key combinations
if (key.shift && key.name === "tab") { /* Shift+Tab */ }

// Command/Meta+Key (Mac)
if (key.meta && key.name === "c") { /* Command+C */ }

Component Input Events

InputRenderable Events

import { InputRenderable } from "@opentui/core"

const input = new InputRenderable()

// Submit on Enter
input.on("submit", (value: string) => {
  console.log("Submitted:", value)
})

// Change on every keystroke
input.on("change", (value: string) => {
  console.log("Changed:", value)
})

// Focus/Blur
input.on("focus", () => {
  console.log("Input focused")
})

input.on("blur", () => {
  console.log("Input blurred")
})

SelectRenderable Events

import { SelectRenderable } from "@opentui/core"

const select = new SelectRenderable({
  options: [
    { label: "Option 1", value: "1" },
    { label: "Option 2", value: "2" },
  ],
})

select.on("change", (value: string) => {
  console.log("Selected:", value)
})

select.on("submit", (value: string) => {
  console.log("Submitted:", value)
})

ScrollBoxRenderable Events

import { ScrollBoxRenderable } from "@opentui/core"

const scrollBox = new ScrollBoxRenderable()

scrollBox.on("scroll", (scrollOffset: number) => {
  console.log("Scrolled to:", scrollOffset)
})

Mouse Events

// Mouse click
renderer.on("mouse", (event: MouseEvent) => {
  console.log(event.x, event.y)    // Position
  console.log(event.button)        // 'left' | 'middle' | 'right'
  console.log(event.action)        // 'click' | 'drag' | 'scroll'
  console.log(event.shift)         // Modifiers
  console.log(event.ctrl)
  console.log(event.meta)
})

// Component-specific
box.on("click", (event: MouseEvent) => {
  console.log("Box clicked at:", event.x, event.y)
})

Clipboard Paste Events

renderer.on("paste", (text: string) => {
  console.log("Pasted:", text)
})

Focus Management

// Set focus programmatically
input.focus()

// Check if focused
if (input.isFocused()) {
  console.log("Input is focused")
}

// Blur (remove focus)
input.blur()

// Focus next/previous (Tab navigation)
renderer.focusNext()
renderer.focusPrevious()

Custom Key Maps

const keyMap = {
  "ctrl+s": () => save(),
  "ctrl+c": () => copy(),
  "ctrl+v": () => paste(),
  "ctrl+z": () => undo(),
  "ctrl+shift+z": () => redo(),
  "escape": () => cancel(),
  "enter": () => confirm(),
  "q": () => quit(),
}

renderer.on("key", (key: KeyEvent) => {
  const combo = [
    key.ctrl ? "ctrl" : null,
    key.shift ? "shift" : null,
    key.name,
  ].filter(Boolean).join("+")

  if (keyMap[combo]) {
    keyMap[combo]()
  }
})

Event Patterns

Debounce Input

let debounceTimer: NodeJS.Timeout | null = null

input.on("change", (value: string) => {
  if (debounceTimer) clearTimeout(debounceTimer)

  debounceTimer = setTimeout(() => {
    console.log("Debounced:", value)
  }, 300)
})

Keyboard Navigation

let selectedIndex = 0
const items = [/* ... */]

renderer.on("key", (key: KeyEvent) => {
  if (key.name === "down" || (key.name === "tab" && !key.shift)) {
    selectedIndex = Math.min(selectedIndex + 1, items.length - 1)
  }
  if (key.name === "up" || (key.name === "tab" && key.shift)) {
    selectedIndex = Math.max(selectedIndex - 1, 0)
  }
})

Global Shortcuts

// Always active shortcuts
renderer.on("key", (key: KeyEvent) => {
  if (key.name === "c" && key.ctrl) {
    renderer.destroy()
    process.exit(0)
  }

  if (key.name === "?" && key.shift) {
    toggleHelp()
  }
})

// Context-sensitive shortcuts
function handleShortcuts(key: KeyEvent) {
  if (input.isFocused()) {
    // Input-specific shortcuts
    if (key.name === "escape") {
      input.blur()
    }
  } else {
    // Global shortcuts
    if (key.name === "/") {
      input.focus()
    }
  }
}

Reference

• KeyEvent API: OpenTUI core types
• MouseEvent API: OpenTUI core types
• Examples: .search-data/research/opentui/resources.md

OpenTUI Layout Guide (Yoga Flexbox)

OpenTUI uses the Yoga layout engine for CSS Flexbox-like layouts.

Yoga Layout Properties

Container Properties

import { GroupRenderable } from "@opentui/core"

const container = new GroupRenderable()
container.setStyle({
  // Main axis direction
  flexDirection: "row",        // 'row' | 'column' | 'row-reverse' | 'column-reverse'

  // Main axis alignment
  justifyContent: "flex-start", // 'flex-start' | 'center' | 'flex-end' | 'space-between' | 'space-around' | 'space-evenly'

  // Cross axis alignment
  alignItems: "flex-start",    // 'flex-start' | 'center' | 'flex-end' | 'stretch'

  // Multiple lines alignment (when wrapping)
  alignContent: "flex-start",  // 'flex-start' | 'center' | 'flex-end' | 'stretch' | 'space-between' | 'space-around'

  // Wrapping
  flexWrap: "nowrap",          // 'nowrap' | 'wrap' | 'wrap-reverse'

  // Gap between items
  gap: 1,                      // number
  rowGap: 1,
  columnGap: 1,
})

Child Properties

child.setStyle({
  // Grow to fill available space
  flexGrow: 1,                 // number (0 = don't grow)

  // Shrink when needed
  flexShrink: 1,               // number (1 = can shrink)

  // Base size on main axis
  flexBasis: "auto",           // number | 'auto'

  // Alignment override
  alignSelf: "auto",           // 'auto' | 'flex-start' | 'center' | 'flex-end' | 'stretch'

  // Dimensions
  width: 80,                   // number | 'auto'
  height: 24,                  // number | 'auto'
  minWidth: 10,
  minHeight: 5,
  maxWidth: 100,
  maxHeight: 30,

  // Position (when parent is relative)
  position: "relative",        // 'relative' | 'absolute'
  top: 0,
  left: 0,
  right: 0,
  bottom: 0,
})

Absolute Positioning

const parent = new GroupRenderable()
parent.setStyle({ width: 80, height: 24, position: "relative" })

const absoluteChild = new BoxRenderable()
absoluteChild.setStyle({
  position: "absolute",
  top: 2,
  left: 2,
  width: 20,
  height: 5,
})

Common Layout Patterns

Center Content

const container = new GroupRenderable()
container.setStyle({
  width: 80,
  height: 24,
  justifyContent: "center",
  alignItems: "center",
})

Sidebar Layout

const root = new GroupRenderable()
root.setStyle({
  flexDirection: "row",
  width: "100%",
  height: "100%",
})

const sidebar = new BoxRenderable()
sidebar.setStyle({ width: 20, flexGrow: 0 })

const main = new BoxRenderable()
main.setStyle({ flexGrow: 1 })

root.add(sidebar)
root.add(main)

Vertical Form

const form = new GroupRenderable()
form.setStyle({
  flexDirection: "column",
  gap: 1,
  width: 60,
})

const input1 = new InputRenderable()
const input2 = new InputRenderable()
const button = new BoxRenderable()

form.add(input1)
form.add(input2)
form.add(button)

Responsive Layout

function createResponsiveLayout(width: number) {
  const container = new GroupRenderable()

  if (width > 80) {
    container.setStyle({ flexDirection: "row" })
  } else {
    container.setStyle({ flexDirection: "column" })
  }

  return container
}

Layout Debugging

// Enable layout borders
box.setStyle({
  borderStyle: "single",
  borderColor: new Color(255, 0, 0),
})

// Check computed layout
console.log(box.getComputedLayout())
// { left: 0, top: 0, width: 80, height: 24 }

Reference

• Yoga Documentation: https://yogalayout.com/docs/
• OpenTUI Examples: .search-data/research/opentui/resources.md

OpenTUI Styling & Colors

Color System (RGBA)

OpenTUI uses an RGBA color class for full color support.

Creating Colors

import { Color, parseColor } from "@opentui/core"

// From RGB integers (0-255)
const red = new Color(255, 0, 0)

// From RGB floats (0.0-1.0)
const blue = Color.fromValues(0.0, 0.0, 1.0)

// From hex string
const green = parseColor("#00FF00")

// From CSS color name
const yellow = parseColor("yellow")

// Transparent color
const transparent = parseColor("transparent")

// With alpha
const semiTransparentRed = new Color(255, 0, 0, 0.5)

Color Methods

const color = new Color(255, 0, 0)

// Get values
console.log(color.r)        // Red (0-255)
console.log(color.g)        // Green (0-255)
console.log(color.b)        // Blue (0-255)
console.log(color.a)        // Alpha (0.0-1.0)

// Convert formats
console.log(color.toHex())          // "#FF0000"
console.log(color.toRGB())          // "rgb(255, 0, 0)"
console.log(color.toRGBA())         // "rgba(255, 0, 0, 1)"

// Lighten/darken
const lighter = color.lighten(0.2)
const darker = color.darken(0.2)

Supported Color Formats

// Hex formats
parseColor("#F00")
parseColor("#FF0000")
parseColor("#FF0000FF")

// RGB formats
parseColor("rgb(255, 0, 0)")
parseColor("rgba(255, 0, 0, 0.5)")

// CSS color names
parseColor("red")
parseColor("blue")
parseColor("green")
parseColor("yellow")
parseColor("cyan")
parseColor("magenta")
parseColor("white")
parseColor("black")
parseColor("gray")
parseColor("grey")

Style Properties

Border Styles

box.setStyle({
  // Border type
  borderStyle: "single",     // 'single' | 'double' | 'round' | 'bold' | 'dashed' | 'none'

  // Border color
  borderColor: new Color(255, 255, 255),

  // Text decoration
  textDecoration: "underline", // 'underline' | 'bold' | 'dim' | 'italic' | 'blink' | 'inverse' | 'hidden' | 'strikethrough'
})

Background & Foreground

box.setStyle({
  backgroundColor: new Color(30, 30, 30),
  foregroundColor: new Color(255, 255, 255),
})

Spacing

box.setStyle({
  // Padding (inside border)
  paddingTop: 1,
  paddingBottom: 1,
  paddingLeft: 2,
  paddingRight: 2,
  padding: 1, // Shorthand for all sides

  // Margin (outside border)
  marginTop: 1,
  marginBottom: 1,
  marginLeft: 1,
  marginRight: 1,
  margin: 1, // Shorthand for all sides
})

Themes

Creating a Theme

const theme = {
  primary: new Color(100, 149, 237),    // Cornflower blue
  secondary: new Color(255, 165, 0),    // Orange
  success: new Color(46, 204, 113),     // Green
  danger: new Color(231, 76, 60),       // Red
  warning: new Color(241, 196, 15),     // Yellow
  info: new Color(52, 152, 219),        // Blue

  bg: {
    default: new Color(30, 30, 30),
    muted: new Color(50, 50, 50),
    elevated: new Color(70, 70, 70),
  },

  fg: {
    default: new Color(255, 255, 255),
    muted: new Color(180, 180, 180),
  },

  border: {
    default: new Color(100, 100, 100),
    focused: new Color(100, 149, 237),
  },
}

Using Themes

function createPrimaryBox(text: string) {
  const box = new BoxRenderable()
  box.setStyle({
    backgroundColor: theme.bg.elevated,
    borderColor: theme.primary,
    foregroundColor: theme.fg.default,
    borderStyle: "single",
    paddingLeft: 2,
    paddingRight: 2,
  })
  return box
}

function createDangerButton(text: string) {
  const button = new BoxRenderable()
  button.setStyle({
    backgroundColor: theme.danger,
    foregroundColor: new Color(255, 255, 255),
    borderStyle: "none",
    paddingLeft: 2,
    paddingRight: 2,
  })
  return button
}

Text Styling

const text = new TextRenderable("Hello, World!")
text.setStyle({
  foregroundColor: new Color(255, 255, 255),
  textDecoration: "bold", // Can combine: "bold underline"
})

// Multiple styles
const fancyText = new TextRenderable()
fancyText.setStyle({
  foregroundColor: new Color(255, 0, 0),
  textDecoration: "bold underline italic",
})

Dynamic Styling

// Hover effect
box.on("mouseover", () => {
  box.setStyle({ backgroundColor: new Color(50, 50, 50) })
})

box.on("mouseout", () => {
  box.setStyle({ backgroundColor: new Color(30, 30, 30) })
})

// Focus state
input.on("focus", () => {
  input.setStyle({ borderColor: theme.primary })
})

input.on("blur", () => {
  input.setStyle({ borderColor: theme.border.default })
})

Color Utilities

// Blend colors
function blendColors(color1: Color, color2: Color, ratio: number): Color {
  const r = color1.r * (1 - ratio) + color2.r * ratio
  const g = color1.g * (1 - ratio) + color2.g * ratio
  const b = color1.b * (1 - ratio) + color2.b * ratio
  return new Color(r, g, b)
}

// Gradient for text (simulated)
const gradientColors = [
  new Color(255, 0, 0),
  new Color(255, 165, 0),
  new Color(255, 255, 0),
]

Terminal Color Limitations

True Color Support

Most modern terminals support 24-bit true color (16 million colors).

Fallback for Limited Terminals

function getSafeColor(): Color {
  // Check terminal capabilities
  const supportsTrueColor = process.env.COLORTERM === "truecolor" ||
                            process.env.TERM === "xterm-256color"

  if (supportsTrueColor) {
    return new Color(100, 149, 237)
  } else {
    // Fallback to 256-color palette
    return new Color(100, 149, 237)
  }
}

Common Style Patterns

Card Component

function createCard(title: string, content: string) {
  const card = new BoxRenderable()
  card.setStyle({
    borderStyle: "single",
    borderColor: theme.border.default,
    backgroundColor: theme.bg.default,
    padding: 1,
  })

  const titleText = new TextRenderable(title)
  titleText.setStyle({
    foregroundColor: theme.primary,
    textDecoration: "bold",
  })

  const contentText = new TextRenderable(content)

  const container = new GroupRenderable()
  container.setStyle({ flexDirection: "column", gap: 1 })
  container.add(titleText)
  container.add(contentText)

  card.add(container)
  return card
}

Button Component

function createButton(label: string, variant: "primary" | "secondary") {
  const button = new BoxRenderable()
  const colors = variant === "primary" ? {
    bg: theme.primary,
    fg: new Color(255, 255, 255),
  } : {
    bg: theme.bg.elevated,
    fg: theme.fg.default,
  }

  button.setStyle({
    backgroundColor: colors.bg,
    foregroundColor: colors.fg,
    borderStyle: "single",
    borderColor: theme.border.default,
    paddingLeft: 2,
    paddingRight: 2,
  })

  const text = new TextRenderable(label)
  button.add(text)

  return button
}

Reference

• Color API: OpenTUI core types
• Terminal Colors: https://gist.github.com/XVilka/8346728
• Examples: .search-data/research/opentui/resources.md

OpenTUI Testing

Testing Utilities

OpenTUI provides testing utilities for component testing.

import { createTestRenderer } from "@opentui/core/testing"

// Create test renderer (no terminal required)
const testRenderer = await createTestRenderer()

// Use test renderer like normal renderer
const box = new BoxRenderable()
testRenderer.getRoot().add(box)

testRenderer.render()

Mocking Keyboard Input

import { createTestRenderer } from "@opentui/core/testing"

const renderer = await createTestRenderer()

// Mock keyboard events
renderer.simulateKey({
  name: "enter",
  sequence: "\r",
  ctrl: false,
  meta: false,
  shift: false,
})

// Simulate Ctrl+C
renderer.simulateKey({
  name: "c",
  sequence: "\x03",
  ctrl: true,
  meta: false,
  shift: false,
})

Mocking Mouse Input

// Mock mouse clicks
renderer.simulateMouse({
  x: 10,
  y: 5,
  button: "left",
  action: "click",
  shift: false,
  ctrl: false,
  meta: false,
})

// Mock mouse drag
renderer.simulateMouse({
  x: 15,
  y: 10,
  button: "left",
  action: "drag",
  shift: false,
  ctrl: false,
  meta: false,
})

Testing Components

import { createTestRenderer } from "@opentui/core/testing"
import { InputRenderable } from "@opentui/core"

describe("Input Component", () => {
  it("should emit submit on enter", async () => {
    const renderer = await createTestRenderer()
    const input = new InputRenderable()

    let submittedValue: string | null = null
    input.on("submit", (value) => {
      submittedValue = value
    })

    renderer.getRoot().add(input)

    // Simulate typing
    input.setValue("test input")

    // Simulate Enter key
    renderer.simulateKey({ name: "enter", sequence: "\r", ctrl: false, meta: false, shift: false })

    // Assert
    expect(submittedValue).toBe("test input")
  })

  it("should focus on click", async () => {
    const renderer = await createTestRenderer()
    const input = new InputRenderable()
    renderer.getRoot().add(input)

    expect(input.isFocused()).toBe(false)

    // Simulate click
    renderer.simulateMouse({
      x: 5,
      y: 0,
      button: "left",
      action: "click",
      shift: false,
      ctrl: false,
      meta: false,
    })

    expect(input.isFocused()).toBe(true)
  })
})

Testing Layout

it("should layout children correctly", async () => {
  const renderer = await createTestRenderer()
  const group = new GroupRenderable()

  group.setStyle({
    flexDirection: "row",
    width: 80,
    height: 10,
  })

  const box1 = new BoxRenderable()
  box1.setStyle({ width: 20 })

  const box2 = new BoxRenderable()
  box2.setStyle({ flexGrow: 1 })

  group.add(box1)
  group.add(box2)

  renderer.getRoot().add(group)
  renderer.render()

  const layout1 = box1.getComputedLayout()
  const layout2 = box2.getComputedLayout()

  expect(layout1.width).toBe(20)
  expect(layout2.width).toBe(60) // 80 - 20
})

Testing Animations

import { Timeline } from "@opentui/core"

it("should animate property", async () => {
  const renderer = await createTestRenderer()
  const box = new BoxRenderable()

  const timeline = new Timeline({ duration: 1000 })
  timeline.to(box, { backgroundColor: new Color(255, 0, 0) })

  timeline.play()

  // Wait for animation
  await new Promise(resolve => setTimeout(resolve, 1000))

  const style = box.getStyle()
  expect(style.backgroundColor).toEqual(new Color(255, 0, 0))
})

Testing Focus Management

it("should handle focus navigation", async () => {
  const renderer = await createTestRenderer()

  const input1 = new InputRenderable()
  const input2 = new InputRenderable()

  renderer.getRoot().add(input1)
  renderer.getRoot().add(input2)

  // Focus first input
  input1.focus()
  expect(input1.isFocused()).toBe(true)

  // Tab to next
  renderer.simulateKey({ name: "tab", sequence: "\t", ctrl: false, meta: false, shift: false })

  expect(input1.isFocused()).toBe(false)
  expect(input2.isFocused()).toBe(true)
})

Testing Render Output

it("should render correctly", async () => {
  const renderer = await createTestRenderer()
  const box = new BoxRenderable()
  box.setStyle({
    borderStyle: "single",
    width: 10,
    height: 5,
  })

  renderer.getRoot().add(box)
  renderer.render()

  // Get rendered output
  const output = renderer.getOutput()

  // Assert output contains expected content
  expect(output).toContain("┌")
  expect(output).toContain("─")
  expect(output).toContain("┐")
})

Integration Testing

describe("Form Integration", () => {
  it("should submit form with validation", async () => {
    const renderer = await createTestRenderer()

    const form = new GroupRenderable()
    form.setStyle({ flexDirection: "column" })

    const usernameInput = new InputRenderable()
    const passwordInput = new InputRenderable()
    const submitButton = new BoxRenderable()

    form.add(usernameInput)
    form.add(passwordInput)
    form.add(submitButton)

    renderer.getRoot().add(form)

    // Fill form
    usernameInput.setValue("user@example.com")
    passwordInput.setValue("password123")

    // Simulate submit
    submitButton.emit("click")

    // Assert form data
    expect(getFormData()).toEqual({
      username: "user@example.com",
      password: "password123",
    })
  })
})

Test Helpers

Create Component Factory

function createTestBox(props: any = {}) {
  const box = new BoxRenderable()
  box.setStyle({
    width: props.width || 10,
    height: props.height || 5,
    borderStyle: props.borderStyle || "single",
    ...props.style,
  })
  return box
}

Wait for Render

async function waitForRender(renderer: any, maxWait = 1000) {
  return new Promise((resolve) => {
    const startTime = Date.now()
    const checkRender = () => {
      if (Date.now() - startTime > maxWait) {
        resolve(false)
        return
      }
      requestAnimationFrame(checkRender)
    }
    checkRender()
  })
}

Capture Console Output

function captureConsole() {
  const logs: string[] = []
  const originalLog = console.log

  console.log = (...args: any[]) => {
    logs.push(args.join(" "))
  }

  return {
    getLogs: () => logs,
    restore: () => {
      console.log = originalLog
    },
  }
}

Testing Best Practices

1. Isolate Tests: Each test should be independent 2. Mock External Dependencies: Don't rely on real terminal 3. Test User Interactions: Simulate keyboard/mouse events 4. Assert Component State: Check values, not just rendering 5. Test Edge Cases: Empty inputs, invalid values, etc. 6. Clean Up: Destroy renderers after tests

Reference

• Testing Utilities: @opentui/core/testing
• Examples: .search-data/research/opentui/resources.md