terminaltui

Build interactive terminal websites and apps. Write pages, get a TUI, distribute via npx.

Quick Start

npx terminaltui init my-site
cd my-site
npx terminaltui dev

Or try a built-in demo instantly:

npx terminaltui demo restaurant

What is this?

terminaltui turns declarative TypeScript into fully interactive terminal applications with keyboard navigation, animations, theming, and ASCII art. Users run your app with a single npx command. No browser, no Electron, no React.

Project Structure

Each page is its own file. A top-level config.ts handles theme and settings.

my-site/
├── config.ts          # theme, banner, global settings
├── pages/
│   ├── home.ts        # landing page
│   ├── about.ts       # /about
│   ├── projects/
│   │   ├── index.ts   # /projects
│   │   └── [slug].ts  # /projects/:slug (dynamic route)
│   └── contact.ts     # /contact
├── api/
│   └── stats.ts       # GET /api/stats
└── components/        # reusable blocks

config.ts

import { defineConfig } from "terminaltui";

export default defineConfig({
  name: "My Site",
  theme: "cyberpunk",
  banner: { text: "MY SITE", font: "ANSI Shadow" },
});

pages/about.ts

import { card, timeline } from "terminaltui";

export const metadata = { label: "About", icon: "?" };

export default function About() {
  return [
    card({ title: "About Me", body: "Full-stack developer based in Portland." }),
    timeline([
      { date: "2024", title: "Started terminaltui" },
      { date: "2023", title: "Joined Acme Corp" },
    ]),
  ];
}

Single-file site.config.ts still works. Use terminaltui migrate to convert existing projects.

Features

30+ Components

Cards, tables, timelines, forms, progress bars, galleries, tabs, accordions, and more.

row([
  col([card({ title: "Revenue", body: "$1.2M" })], { span: 4 }),
  col([card({ title: "Users", body: "45,231" })], { span: 4 }),
  col([card({ title: "Uptime", body: "99.97%" })], { span: 4 }),
])

12-Column Grid System

Bootstrap-style responsive grid with automatic spatial navigation.

row([
  col([statsCard], { span: 3, xs: 12 }),
  col([chartCard], { span: 9, xs: 12 }),
], { gap: 1 })

Breakpoints: xs (<60 cols), sm (60-89), md (90-119), lg (>=120). Rows auto-wrap.

Spatial Navigation

Arrow keys move to the nearest item on screen -- like a TV remote. No configuration needed. Works automatically with all layouts.

| Key | Action | |-----|--------| | Up/Down or j/k | Move to nearest item above/below | | Left/Right or h/l | Move to nearest item left/right | | Enter | Activate | | Escape | Go back | | Tab | Sequential fallback | | 1-9 | Jump to page |

10 Themes

cyberpunk, dracula, nord, monokai, solarized, gruvbox, catppuccin, tokyoNight, rosePine, hacker. Plus custom themes.

export default defineConfig({ theme: "dracula" });

ASCII Art Engine

14 fonts, 15 scenes, 30+ icons, data visualization, image-to-ASCII conversion.

Forms & Inputs

TextInput, TextArea, Select, Checkbox, Toggle, RadioGroup, NumberInput, SearchInput, Button. Validation, submission, notifications.

File-Based API Routes

// api/stats.ts
export async function GET() {
  return { users: 45231, uptime: 99.97 };
}

File path maps to endpoint: api/stats.ts -> GET /api/stats. Framework starts a local server automatically.

Reactive State

const count = createState({ visitors: 0 });

dynamic(() => [text(`Visitors: ${count.get("visitors")}`)]);

createState, computed, dynamic, createPersistentState, fetcher, request, liveData.

Demos

No setup needed -- run any demo straight from npm:

npx terminaltui demo restaurant
npx terminaltui demo dashboard
npx terminaltui demo band
npx terminaltui demo coffee-shop
npx terminaltui demo conference
npx terminaltui demo developer-portfolio
npx terminaltui demo freelancer
npx terminaltui demo startup

| Demo | Theme | Highlights | |------|-------|------------| | Restaurant | gruvbox | Tabbed menu, reservation form, split layout | | Dashboard | hacker | Live API data, persistent state, parameterized routes | | Band | rosePine | Album cards, tour dates, mailing list | | Coffee Shop | catppuccin | Tabbed menu, catering form | | Conference | nord | Schedule tabs, speaker grid, sponsor tiers | | Developer Portfolio | cyberpunk | Skill bars, sparklines, project grid | | Freelancer | custom | Testimonial quotes, contact form | | Startup | tokyoNight | Pricing tiers, feature accordion | | Server Dashboard | hacker | System metrics, container table, log stream |

Restaurant

Dashboard (live API data)

Tetris (yes, really — a fully playable game built on the framework)

CLI

terminaltui init [template]    # scaffold a new project
terminaltui dev [path]         # compile and run (auto-detects project type)
terminaltui build              # bundle for npm publish
terminaltui migrate            # convert site.config.ts to file-based routing
terminaltui demo [name]        # run a built-in demo
terminaltui create             # interactive prompt builder
terminaltui convert            # AI-assisted website conversion
terminaltui test               # headless emulator tests
terminaltui art                # manage ASCII art assets

See It Live

npx omar-musayev

A real portfolio built with terminaltui.

For AI Agents

terminaltui ships with claude/SKILL.md -- a 2,000+ line API reference designed for AI code generation. The terminaltui create and terminaltui convert commands generate tailored prompts for Claude Code.

The TUI emulator (terminaltui/emulator) provides headless testing: spawn the app in a PTY, read the screen, send keystrokes, assert content.

Documentation

| Doc | What's in it | |-----|-------------| | claude/SKILL.md | Full API reference -- every function, type, component | | docs/components.md | Component catalog with examples | | docs/layouts.md | Grid system, spatial navigation, layout patterns | | CHANGELOG.md | Version history | | ARCHITECTURE.md | Codebase structure and design decisions |

Tech Stack

• TypeScript -- strict mode, zero any in public API
• 1 dependency (esbuild) -- everything else is Node built-ins
• 2,185+ tests across unit, integration, emulator, and demo suites
• Apple Terminal compatible -- auto-detects and uses 256-color fallback

Contributing

Issues and PRs welcome at github.com/OmarMusayev/terminaltui.

License

MIT