Building Your First App

This tutorial will guide you through building a complete terminal user interface application with OpenTUI, from setup to deployment.

What We’ll Build

We’ll create a task manager application featuring:

A list of tasks with selection
Input field for adding new tasks
Status bar showing key bindings
Responsive layout that adapts to terminal size

Prerequisites

Make sure you have Bun installed:

curl -fsSL https://bun.sh/install | bash

Install OpenTUI

Create a new project and install OpenTUI:

mkdir task-manager
cd task-manager
bun init -y
bun add @opentui/core

Create the Basic Structure

Create index.ts with the basic renderer setup:

import { createCliRenderer } from "@opentui/core"

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

renderer.setBackgroundColor("#001122")
renderer.start()

console.log("Task Manager initialized!")

Run it to verify the setup:

bun index.ts

You should see a dark blue background. Press ` to open the console, or Ctrl+C to exit.

Add a Header

Let’s add a header with the app title:

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

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

renderer.setBackgroundColor("#001122")

// Create header
const header = new BoxRenderable(renderer, {
  id: "header",
  width: "auto",
  height: 3,
  backgroundColor: "#3b82f6",
  borderStyle: "single",
  alignItems: "center",
  border: true,
})

const headerText = new TextRenderable(renderer, {
  id: "header-text",
  content: "TASK MANAGER",
  fg: "#ffffff",
})

header.add(headerText)
renderer.root.add(header)

renderer.start()

Create the Task List

Add a scrollable list to display tasks:

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

// ... previous header code ...

// Task data
const tasks = [
  { name: "Write documentation", completed: false },
  { name: "Fix bug in parser", completed: true },
  { name: "Review pull requests", completed: false },
]

// Create task list
const taskList = new SelectRenderable(renderer, {
  id: "task-list",
  width: "auto",
  height: "auto",
  flexGrow: 1,
  options: tasks.map((task, i) => ({
    name: `${task.completed ? "✓" : "○"} ${task.name}`,
    description: task.completed ? "Completed" : "Pending",
  })),
  position: "relative",
})

taskList.on(SelectRenderableEvents.ITEM_SELECTED, (index, option) => {
  console.log(`Selected task: ${tasks[index].name}`)
  // Toggle completion
  tasks[index].completed = !tasks[index].completed
  updateTaskList()
})

function updateTaskList() {
  taskList.setOptions(
    tasks.map((task) => ({
      name: `${task.completed ? "✓" : "○"} ${task.name}`,
      description: task.completed ? "Completed" : "Pending",
    }))
  )
}

renderer.root.add(taskList)
taskList.focus()

Add Input for New Tasks

Create an input field to add new tasks:

import {
  createCliRenderer,
  BoxRenderable,
  TextRenderable,
  SelectRenderable,
  SelectRenderableEvents,
  InputRenderable,
  InputRenderableEvents,
} from "@opentui/core"

// ... previous code ...

// Create input container
const inputContainer = new BoxRenderable(renderer, {
  id: "input-container",
  width: "auto",
  height: 5,
  borderStyle: "single",
  border: true,
  padding: 1,
})

const inputLabel = new TextRenderable(renderer, {
  id: "input-label",
  content: "New Task:",
  fg: "#00FFFF",
})

const taskInput = new InputRenderable(renderer, {
  id: "task-input",
  width: "auto",
  placeholder: "Enter task name...",
  focusedBackgroundColor: "#1a1a1a",
})

taskInput.on(InputRenderableEvents.ENTER, (value) => {
  if (value.trim()) {
    tasks.push({ name: value, completed: false })
    updateTaskList()
    taskInput.value = ""
    console.log(`Added task: ${value}`)
  }
})

inputContainer.add(inputLabel)
inputContainer.add(taskInput)
renderer.root.add(inputContainer)

Create a footer showing available keyboard shortcuts:

// Create footer
const footer = new BoxRenderable(renderer, {
  id: "footer",
  width: "auto",
  height: 3,
  backgroundColor: "#1e40af",
  borderStyle: "single",
  alignItems: "center",
  justifyContent: "center",
  border: true,
})

const footerText = new TextRenderable(renderer, {
  id: "footer-text",
  content: "↑/↓: Navigate | Enter: Toggle | Tab: Switch Focus | Ctrl+C: Exit",
  fg: "#ffffff",
})

footer.add(footerText)
renderer.root.add(footer)

Add Tab key navigation between the list and input:

import type { KeyEvent } from "@opentui/core"

let focusedElement: "list" | "input" = "list"

renderer.keyInput.on("keypress", (key: KeyEvent) => {
  if (key.name === "tab") {
    if (focusedElement === "list") {
      taskList.blur()
      taskInput.focus()
      focusedElement = "input"
    } else {
      taskInput.blur()
      taskList.focus()
      focusedElement = "list"
    }
  }
})

Add Dynamic Updates

Make the UI update in real-time with a counter:

// Add a status indicator
const statusText = new TextRenderable(renderer, {
  id: "status",
  content: "",
  position: "absolute",
  right: 2,
  top: 1,
  fg: "#00FF00",
})
renderer.root.add(statusText)

// Update status every second
setInterval(() => {
  const completed = tasks.filter((t) => t.completed).length
  const total = tasks.length
  statusText.content = `${completed}/${total} completed`
}, 1000)

Complete Application

Here’s the full code:

import {
  createCliRenderer,
  BoxRenderable,
  TextRenderable,
  SelectRenderable,
  SelectRenderableEvents,
  InputRenderable,
  InputRenderableEvents,
  type KeyEvent,
} from "@opentui/core"

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

renderer.setBackgroundColor("#001122")

// Data
const tasks = [
  { name: "Write documentation", completed: false },
  { name: "Fix bug in parser", completed: true },
  { name: "Review pull requests", completed: false },
]

let focusedElement: "list" | "input" = "list"

// Header
const header = new BoxRenderable(renderer, {
  id: "header",
  width: "auto",
  height: 3,
  backgroundColor: "#3b82f6",
  borderStyle: "single",
  alignItems: "center",
  border: true,
})

const headerText = new TextRenderable(renderer, {
  id: "header-text",
  content: "TASK MANAGER",
  fg: "#ffffff",
})

header.add(headerText)

// Task List
const taskList = new SelectRenderable(renderer, {
  id: "task-list",
  width: "auto",
  height: "auto",
  flexGrow: 1,
  options: [],
})

function updateTaskList() {
  taskList.setOptions(
    tasks.map((task) => ({
      name: `${task.completed ? "✓" : "○"} ${task.name}`,
      description: task.completed ? "Completed" : "Pending",
    }))
  )
}

taskList.on(SelectRenderableEvents.ITEM_SELECTED, (index) => {
  tasks[index].completed = !tasks[index].completed
  updateTaskList()
})

// Input
const inputContainer = new BoxRenderable(renderer, {
  id: "input-container",
  width: "auto",
  height: 5,
  borderStyle: "single",
  border: true,
  padding: 1,
})

const inputLabel = new TextRenderable(renderer, {
  id: "input-label",
  content: "New Task:",
  fg: "#00FFFF",
})

const taskInput = new InputRenderable(renderer, {
  id: "task-input",
  width: "auto",
  placeholder: "Enter task name...",
})

taskInput.on(InputRenderableEvents.ENTER, (value) => {
  if (value.trim()) {
    tasks.push({ name: value, completed: false })
    updateTaskList()
    taskInput.value = ""
  }
})

inputContainer.add(inputLabel)
inputContainer.add(taskInput)

// Footer
const footer = new BoxRenderable(renderer, {
  id: "footer",
  width: "auto",
  height: 3,
  backgroundColor: "#1e40af",
  borderStyle: "single",
  alignItems: "center",
  justifyContent: "center",
  border: true,
})

const footerText = new TextRenderable(renderer, {
  id: "footer-text",
  content: "↑/↓: Navigate | Enter: Toggle | Tab: Switch Focus | Ctrl+C: Exit",
  fg: "#ffffff",
})

footer.add(footerText)

// Status
const statusText = new TextRenderable(renderer, {
  id: "status",
  content: "",
  position: "absolute",
  right: 2,
  top: 1,
  fg: "#00FF00",
})

// Assemble UI
renderer.root.add(header)
renderer.root.add(taskList)
renderer.root.add(inputContainer)
renderer.root.add(footer)
renderer.root.add(statusText)

// Keyboard navigation
renderer.keyInput.on("keypress", (key: KeyEvent) => {
  if (key.name === "tab") {
    if (focusedElement === "list") {
      taskList.blur()
      taskInput.focus()
      focusedElement = "input"
    } else {
      taskInput.blur()
      taskList.focus()
      focusedElement = "list"
    }
  }
})

// Update status
setInterval(() => {
  const completed = tasks.filter((t) => t.completed).length
  statusText.content = `${completed}/${tasks.length} completed`
}, 1000)

updateTaskList()
taskList.focus()
renderer.start()

Running Your App

Run your task manager:

bun index.ts

Next Steps

Styling and Colors

Learn about RGBA colors and text styling

Keyboard and Mouse

Handle user input with key events and mouse interactions

Animations

Add smooth animations with the Timeline system

Console Overlay

Debug your app with the built-in console

Common Patterns

Saving Data

Persist tasks to a JSON file:

import { writeFileSync, readFileSync } from "fs"

function saveTasks() {
  writeFileSync("tasks.json", JSON.stringify(tasks, null, 2))
}

function loadTasks() {
  try {
    const data = readFileSync("tasks.json", "utf-8")
    return JSON.parse(data)
  } catch {
    return []
  }
}

// Load on start
const tasks = loadTasks()

// Save when tasks change
taskInput.on(InputRenderableEvents.ENTER, (value) => {
  if (value.trim()) {
    tasks.push({ name: value, completed: false })
    saveTasks()
    updateTaskList()
    taskInput.value = ""
  }
})

Handling Resize

Adapt your layout when the terminal is resized:

renderer.on("resize", (width: number, height: number) => {
  console.log(`Terminal resized to ${width}x${height}`)
  // Layout updates automatically via Yoga
})

Adding Colors

Use different colors for task states:

function updateTaskList() {
  taskList.setOptions(
    tasks.map((task) => ({
      name: task.completed 
        ? `✓ ${task.name}` 
        : `○ ${task.name}`,
      description: task.completed ? "Completed" : "Pending",
    }))
  )
  
  // Custom rendering with colors
  taskList.itemColor = (index) => {
    return tasks[index].completed ? "#00FF00" : "#FFFFFF"
  }
}

Getting Started

Core Concepts

Guides

Framework Integrations

Advanced

Building Your First App

What We’ll Build

Prerequisites

Running Your App

Next Steps

Styling and Colors

Keyboard and Mouse

Animations

Console Overlay

Common Patterns

Saving Data

Handling Resize

Adding Colors

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Framework Integrations

Advanced

​What We’ll Build

​Prerequisites

​Running Your App

​Next Steps

Styling and Colors

Keyboard and Mouse

Animations

Console Overlay

​Common Patterns

​Saving Data

​Handling Resize

​Adding Colors

Build docs developers (and LLMs) love

What We’ll Build

Prerequisites

Running Your App

Next Steps

Common Patterns

Saving Data

Handling Resize

Adding Colors