Quickstart

Get started with OpenTUI in minutes by building your first terminal UI application

Get up and running with OpenTUI by building a simple “Hello World” terminal application. This guide walks you through installation, basic setup, and creating your first interactive TUI.

If you haven’t installed OpenTUI yet, check out the installation guide first.

Prerequisites

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

Create your first app

1. Install OpenTUI

   Install the core package using your preferred package manager:

   bun

   bun add @opentui/core
   

   npm install @opentui/core
   

   yarn add @opentui/core
   

   pnpm add @opentui/core
   
2. Create a basic app

   Create a new file called app.ts with your first terminal UI:

   import { createCliRenderer, Text } from "@opentui/core"
   
   // Create the renderer
   const renderer = await createCliRenderer()
   
   // Create a text component
   const greeting = Text({
     content: "Hello, OpenTUI!",
     fg: "#00FFFF",
   })
   
   // Add to the renderer and display
   renderer.root.add(greeting)
   

   This creates a simple terminal UI that displays cyan-colored text.

3. Run your app

   Execute your application with Bun:

   bun run app.ts
   

   You should see “Hello, OpenTUI!” displayed in cyan in your terminal!

4. Add interactivity

   Let’s make it interactive by adding keyboard handling:

   import { createCliRenderer, Text, Box } from "@opentui/core"
   
   const renderer = await createCliRenderer()
   
   // Create a container
   const container = Box({
     width: "100%",
     height: "100%",
     flexDirection: "column",
     alignItems: "center",
     justifyContent: "center",
     padding: 2,
   })
   
   // Add text
   const greeting = Text({
     content: "Press any key... (Ctrl+C to exit)",
     fg: "#00FFFF",
   })
   
   container.add(greeting)
   renderer.root.add(container)
   
   // Handle keyboard input
   renderer.keyInput.on("keypress", (key) => {
     if (key.ctrl && key.name === "c") {
       renderer.destroy()
       process.exit(0)
     } else {
       greeting.setContent(`You pressed: ${key.name}`)
       renderer.requestRender()
     }
   })
   

   Now your app responds to keyboard input!

5. Add layout and styling

   Create a more complex layout with multiple components:

   import { createCliRenderer, Text, Box, Input } from "@opentui/core"
   
   const renderer = await createCliRenderer()
   
   // Main container
   const container = Box({
     width: "100%",
     height: "100%",
     flexDirection: "column",
     padding: 2,
     gap: 1,
   })
   
   // Header
   const header = Box({
     width: "100%",
     border: true,
     borderStyle: "rounded",
     padding: 1,
     backgroundColor: "#1a1a1a",
   })
   
   const title = Text({
     content: "My First OpenTUI App",
     fg: "#00FFFF",
     bold: true,
   })
   
   header.add(title)
   
   // Input field
   const input = Input({
     placeholder: "Type something...",
     width: "100%",
   })
   
   input.on("change", (value: string) => {
     console.log("Input changed:", value)
   })
   
   // Add everything
   container.add(header)
   container.add(input)
   renderer.root.add(container)
   
   // Focus the input
   input.focus()
   

   This creates a styled header and an input field with focus management.

Next steps

Now that you’ve built your first OpenTUI app, explore more features:

Core concepts

Learn about renderers, renderables, and the component system

Components

Explore all available UI components

Styling guide

Master colors, text attributes, and styling

Build your first app

Follow a complete tutorial to build a real application

Quick examples

Try these standalone examples to see more features:

Text styling

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

const renderer = await createCliRenderer()

const styled = Text({
  content: [
    bold(fg("#00FFFF", "Bold cyan text")),
    " and ",
    bg("#FF0000", fg("#FFFF00", "yellow on red")),
  ],
})

renderer.root.add(styled)

Flexbox layout

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

const renderer = await createCliRenderer()

const container = Box({
  width: "100%",
  height: "100%",
  flexDirection: "row",
  justifyContent: "space-between",
  padding: 2,
})

container.add(
  Box({
    border: true,
    padding: 1,
    children: [Text({ content: "Left" })],
  })
)

container.add(
  Box({
    border: true,
    padding: 1,
    children: [Text({ content: "Center" })],
  })
)

container.add(
  Box({
    border: true,
    padding: 1,
    children: [Text({ content: "Right" })],
  })
)

renderer.root.add(container)

Interactive list

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

const renderer = await createCliRenderer()

const select = Select({
  items: [
    { label: "Option 1", value: "1" },
    { label: "Option 2", value: "2" },
    { label: "Option 3", value: "3" },
  ],
  width: 30,
  height: 10,
})

select.on("itemSelected", (item) => {
  console.log("Selected:", item)
})

renderer.root.add(select)
select.focus()

Resources

• GitHub Repository
• Example Gallery
• API Reference