Quickstart

This guide walks you through creating a simple interactive terminal application using Kraken TUI. You’ll build a todo list app that demonstrates core concepts: widgets, layout, input handling, and rendering.

Prerequisites: Complete the Installation guide before starting this tutorial.

Choose Your API Style

Kraken TUI offers two APIs with the same underlying performance:

Imperative API — Direct control with explicit widget creation and manipulation
JSX API — Declarative composition with reactive signals (requires @preact/signals-core)

Pick the style that matches your preference. Both examples create the same application.

Imperative API
JSX API

Imperative: Hello World

Let’s start with the simplest possible application:

Create your project file

Create a new file hello.ts:

hello.ts

import { Kraken, Box, Text, KeyCode } from "./ts/src/index";

// Initialize the TUI engine
const app = Kraken.init();

// Create root container
const root = new Box({
  width: "100%",
  height: "100%",
  flexDirection: "column",
  padding: 2,
});

// Create text widget
const label = new Text({
  content: "Hello, Kraken TUI!",
  fg: "#00FF00",
  bold: true,
});

// Build widget tree
root.append(label);
app.setRoot(root);

// Event loop
let running = true;
while (running) {
  app.readInput(16);  // Read input with 16ms timeout (~60fps)
  
  for (const event of app.drainEvents()) {
    if (event.type === "key" && event.keyCode === KeyCode.Escape) {
      running = false;
    }
  }
  
  app.render();  // Render frame
}

// Clean shutdown
app.shutdown();

Run your application

cargo build --manifest-path native/Cargo.toml --release
bun run hello.ts

Press Esc to exit.

How It Works

Initialize — Kraken.init() creates the native context and terminal backend
Compose — Create widgets and build a tree structure using append()
Mount — app.setRoot() attaches your tree to the rendering surface
Loop — Read input → drain events → render (60fps pattern)
Shutdown — app.shutdown() restores terminal state

Interactive Todo List

Now let’s build a more complete application with input handling:

todo.ts

import {
  Kraken,
  Box,
  Text,
  Input,
  Select,
  KeyCode,
} from "./ts/src/index";
import type { KrakenEvent } from "./ts/src/index";

const app = Kraken.init();

// Root container
const root = new Box({
  width: "100%",
  height: "100%",
  flexDirection: "column",
  padding: 1,
  gap: 1,
});

// Header
const header = new Text({
  content: "# Todo List\n\nPress *Tab* to switch focus, *Enter* to add task, *Esc* to quit.",
  format: "markdown",
  fg: "cyan",
});
header.setWidth("100%");
header.setHeight(4);

// Input row
const inputRow = new Box({
  width: "100%",
  flexDirection: "row",
  gap: 2,
});

const inputLabel = new Text({
  content: "New task:",
  bold: true,
  fg: "green",
});
inputLabel.setWidth(10);
inputLabel.setHeight(3);

const input = new Input({
  width: 40,
  height: 3,
  border: "rounded",
  fg: "white",
  maxLength: 100,
});
input.setFocusable(true);

inputRow.append(inputLabel);
inputRow.append(input);

// Todo list
const todos: string[] = ["Learn Kraken TUI", "Build something cool"];

const todoSelect = new Select({
  options: todos,
  width: "100%",
  height: 12,
  border: "single",
  fg: "white",
});
todoSelect.setFocusable(true);

// Status bar
const statusBar = new Text({
  content: "Ready",
  fg: "bright-black",
});
statusBar.setWidth("100%");
statusBar.setHeight(1);

// Assemble tree
root.append(header);
root.append(inputRow);
root.append(todoSelect);
root.append(statusBar);

app.setRoot(root);
input.focus();

// Event loop
let running = true;

while (running) {
  app.readInput(16);
  
  const events: KrakenEvent[] = app.drainEvents();
  for (const event of events) {
    // Quit on Escape
    if (event.type === "key" && event.keyCode === KeyCode.Escape) {
      running = false;
      break;
    }
    
    // Add todo on Enter in input
    if (event.type === "submit" && event.target === input.handle) {
      const value = input.getValue();
      if (value.trim()) {
        todos.push(value);
        todoSelect.addOption(value);
        input.setValue("");
        statusBar.setContent(`Added: "${value}"`);
      }
    }
    
    // Show selected todo
    if (event.type === "change" && event.target === todoSelect.handle) {
      const idx = event.selectedIndex ?? 0;
      const todo = todoSelect.getOption(idx);
      statusBar.setContent(`Selected: "${todo}"`);
    }
  }
  
  if (!running) break;
  app.render();
}

app.shutdown();

Key Concepts

Widget Tree

Widgets are composed hierarchically. Box containers hold children arranged by Flexbox layout.

Handles

Each widget has a handle property — an opaque u32 reference. Use handles to identify event targets.

Event Loop

The host controls timing: readInput() → drainEvents() → render(). Typically 60fps (16ms interval).

Focus Management

Call setFocusable(true) on interactive widgets. Use Tab/Shift+Tab for keyboard traversal.

JSX: Hello World

Using the declarative JSX API with reactive signals:

Install signals dependency

cd ts
bun add @preact/signals-core

Create your project file

Create hello-jsx.tsx:

hello-jsx.tsx

import { Kraken, render, signal, createLoop, KeyCode } from "./ts/src/index";
import { jsx } from "./ts/src/jsx/jsx-runtime";

// Initialize app
const app = Kraken.init();

// Reactive state
const message = signal("Hello, Kraken TUI!");

// JSX tree
const tree = jsx("Box", {
  width: "100%",
  height: "100%",
  flexDirection: "column",
  padding: 2,
  children: jsx("Text", {
    content: message,  // Binds to signal
    fg: "#00FF00",
    bold: true,
  }),
});

// Mount and render
render(tree, app);

// Event loop with createLoop utility
const loop = createLoop({
  app,
  onEvent(event) {
    if (event.type === "key" && event.keyCode === KeyCode.Escape) {
      loop.stop();
    }
  },
});

await loop.start();
app.shutdown();

Configure TypeScript for JSX

Add to tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "kraken-tui"
  }
}

Run your application

cargo build --manifest-path native/Cargo.toml --release
bun run hello-jsx.tsx

How It Works

Signals — signal() creates reactive state that auto-updates the UI
JSX — Declarative tree syntax (transformed to jsx() calls)
Render — render(tree, app) mounts the tree and sets up signal subscriptions
Loop — createLoop() provides async event loop with animation awareness

Interactive Todo List (JSX)

The same todo app using JSX and signals:

todo-jsx.tsx

import {
  Kraken,
  render,
  signal,
  createLoop,
  KeyCode,
} from "./ts/src/index";
import { jsx, jsxs } from "./ts/src/jsx/jsx-runtime";
import type { Widget } from "./ts/src/widget";
import { ffi } from "./ts/src/ffi";

const app = Kraken.init();

// Reactive state
const todos = signal<string[]>(["Learn Kraken TUI", "Build something cool"]);
const status = signal("Ready");

// Widget refs for event handling
let inputWidget: Widget | null = null;
let selectWidget: Widget | null = null;

// Helper to read input value
function getInputValue(handle: number): string {
  const len = ffi.tui_get_content_len(handle);
  if (len <= 0) return "";
  const buf = Buffer.alloc(len + 1);
  const written = ffi.tui_get_content(handle, buf, len + 1);
  return buf.toString("utf-8", 0, written);
}

// JSX tree
const tree = jsxs("Box", {
  width: "100%",
  height: "100%",
  flexDirection: "column",
  padding: 1,
  gap: 1,
  children: [
    // Header
    jsx("Text", {
      key: "header",
      content: "# Todo List\n\nPress *Tab* to switch focus, *Enter* to add, *Esc* to quit.",
      format: "markdown",
      fg: "cyan",
      width: "100%",
      height: 4,
    }),
    
    // Input row
    jsxs("Box", {
      key: "input-row",
      width: "100%",
      flexDirection: "row",
      gap: 2,
      children: [
        jsx("Text", {
          key: "label",
          content: "New task:",
          bold: true,
          fg: "green",
          width: 10,
          height: 3,
        }),
        jsx("Input", {
          key: "input",
          width: 40,
          height: 3,
          border: "rounded",
          fg: "white",
          maxLength: 100,
          focusable: true,
          ref: (w: Widget) => { inputWidget = w; },
        }),
      ],
    }),
    
    // Todo list (reactive to todos signal)
    jsx("Select", {
      key: "todos",
      options: todos,  // Signal binding
      width: "100%",
      height: 12,
      border: "single",
      fg: "white",
      focusable: true,
      ref: (w: Widget) => { selectWidget = w; },
    }),
    
    // Status bar (reactive to status signal)
    jsx("Text", {
      key: "status",
      content: status,
      fg: "bright-black",
      width: "100%",
      height: 1,
    }),
  ],
});

render(tree, app);
if (inputWidget) inputWidget.focus();

// Event loop
const loop = createLoop({
  app,
  onEvent(event) {
    if (event.type === "key" && event.keyCode === KeyCode.Escape) {
      loop.stop();
      return;
    }
    
    // Add todo on Enter
    if (event.type === "submit" && inputWidget && event.target === inputWidget.handle) {
      const value = getInputValue(inputWidget.handle);
      if (value.trim()) {
        todos.value = [...todos.value, value];  // Update signal
        ffi.tui_set_content(inputWidget.handle, Buffer.from(""), 0);
        status.value = `Added: "${value}"`;
      }
    }
    
    // Show selected todo
    if (event.type === "change" && selectWidget && event.target === selectWidget.handle) {
      const idx = event.selectedIndex ?? 0;
      const todo = todos.value[idx];
      status.value = `Selected: "${todo}"`;
    }
  },
});

await loop.start();
app.shutdown();

JSX Benefits

Reactive Updates

Signals automatically update UI when state changes. No manual setText() calls.

Declarative Structure

Tree structure is clear and composable. Easier to read and maintain than imperative code.

Familiar Syntax

If you know React/JSX, you already know the patterns. Props map directly to widget options.

Type Safety

Full TypeScript support with prop validation for each widget type.

Core Concepts Explained

Kraken TUI provides six core widgets:

Widget	Purpose	Key Props
Box	Container with Flexbox layout	`flexDirection`, `gap`, `padding`, `border`
Text	Display text (plain/markdown/code)	`content`, `format`, `fg`, `bold`, `italic`
Input	Single-line text input	`maxLength`, `fg`, `border`, `focusable`
Select	Option list with arrow navigation	`options`, `border`, `focusable`
ScrollBox	Scrollable container (one child)	`border`, `fg`, `bg`
TextArea	Multi-line text editor	`wrapMode`, `fg`, `border`, `focusable`

Layout with Flexbox

Kraken TUI uses Taffy (Rust Flexbox implementation) for layout:

const container = new Box({
  flexDirection: "row",     // horizontal layout
  justifyContent: "center", // center horizontally
  alignItems: "center",     // center vertically
  gap: 2,                   // spacing between children
  padding: 1,               // inner padding
});

Dimensions accept:

Fixed: width: 40 (cells)
Percentage: width: "50%" (of parent)
Fill: width: "100%" (full parent width)
Auto: width: "auto" (content-based)

Event Handling

All events are drained from a buffer each frame:

for (const event of app.drainEvents()) {
  switch (event.type) {
    case "key":
      console.log("Key pressed:", event.keyCode);
      break;
    case "submit":
      console.log("Submit on handle:", event.target);
      break;
    case "change":
      console.log("Value changed:", event.selectedIndex);
      break;
    case "click":
      console.log("Clicked at:", event.x, event.y);
      break;
  }
}

Styling

Colors can be specified as:

Hex: "#FF0000" (RGB)
Named: "red", "cyan", "bright-black" (16 color names)
Indexed: 196 (256 color palette index)

Text decorations:

bold: true
italic: true
underline: true

Borders:

border: "single" — ┌─┐
border: "double" — ╔═╗
border: "rounded" — ╭─╮
border: "none" (default)

Next Steps

Now that you’ve built your first application, explore these topics:

Core Concepts

Deep dive into widgets, layout, and state management

API Reference

Complete API documentation for all widgets and methods

Animation

Add smooth transitions and built-in animation primitives

Theming

Customize appearance with themes and runtime switching

Explore the examples: Check out examples/demo.ts and examples/migration-jsx.tsx in the repository for more complex applications with theming, scrolling, and live updates.

Get Started

Core Concepts

Guides

Choose Your API Style

Imperative: Hello World

How It Works

Interactive Todo List

Key Concepts

Widget Tree

Handles

Event Loop

Focus Management

JSX: Hello World

How It Works

Interactive Todo List (JSX)

JSX Benefits

Reactive Updates

Declarative Structure

Familiar Syntax

Type Safety

Core Concepts Explained

Widget Types

Layout with Flexbox

Event Handling

Styling

Next Steps

Core Concepts

API Reference

Animation

Theming

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Choose Your API Style

​Imperative: Hello World

​How It Works

​Interactive Todo List

​Key Concepts

Widget Tree

Handles

Event Loop

Focus Management

​JSX: Hello World

​How It Works

​Interactive Todo List (JSX)

​JSX Benefits

Reactive Updates

Declarative Structure

Familiar Syntax

Type Safety

​Core Concepts Explained

​Widget Types

​Layout with Flexbox

​Event Handling

​Styling

​Next Steps

Core Concepts

API Reference

Animation

Theming

Build docs developers (and LLMs) love

Choose Your API Style

Imperative: Hello World

How It Works

Interactive Todo List

Key Concepts

JSX: Hello World

How It Works

Interactive Todo List (JSX)

JSX Benefits

Core Concepts Explained

Widget Types

Layout with Flexbox

Event Handling

Styling

Next Steps