TermUI

Build beautiful terminal interfaces with React components you actually own.

Quick Start • Documentation • Components • Adapters • Theming • CLI • Development

TermUI is a comprehensive terminal UI framework for TypeScript, with 101+ components, 9 themes, 12 hooks, and a shadcn-style CLI that copies source code directly into your project. No black-box dependency. No version lock-in. Just code you own and can customize.

npx termui add spinner table select alert

Why TermUI?

The terminal UI landscape in JavaScript is stuck. Ink gives you 5 primitives and leaves the rest to you. Blessed hasn't seen a commit in years. Neither offers a component library with real breadth (charts, forms, data grids, templates), and nothing gives you shadcn-style distribution where you own every line.

TermUI fills that gap:

• 101+ production-ready components: from Spinner and Table to LineChart, DataGrid, LoginFlow, and QRCode
• Copy-paste distribution: npx termui add drops source files into your project; no runtime dependency on the registry
• Themeable everything: swap between Dracula, Nord, Catppuccin, and 6 more with a single command, or create your own
• React mental model: if you know React, you already know TermUI; it's JSX, hooks, and flexbox all the way down
• Built-in testing: @termui/testing gives you renderToString, fireEvent, and waitFor for headless component tests

Quick Start

# Launch the interactive menu
npx termui

# Or use commands directly
npx termui init
npx termui add spinner
npx termui add table select alert
npx termui list

Zero to CLI in 60 seconds

# 1. Scaffold a new project
npx termui create my-cli --template cli

# 2. Add components
cd my-cli
npx termui add spinner table select

# 3. Run your app
npm run dev

Or start with an AI chat interface:

npx termui create my-ai-tool --template ai-assistant

Your first TermUI app

import React from 'react';
import { render } from 'ink';
import { ThemeProvider } from '@termui/core';
import { Spinner, ProgressBar, Alert, Select } from '@termui/components';

function App() {
  return (
    <ThemeProvider>
      <Spinner style="dots" label="Loading…" />
      <ProgressBar value={72} total={100} label="Installing…" />
      <Alert variant="success" title="Done!">
        Your app is ready.
      </Alert>
      <Select
        options={[
          { value: 'npm', label: 'npm' },
          { value: 'pnpm', label: 'pnpm' },
          { value: 'bun', label: 'bun' },
        ]}
        onSubmit={(val) => console.log('Selected:', val)}
      />
    </ThemeProvider>
  );
}

render(<App />);

Component Categories

| Category | Components | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Layout (9) | Box Stack Grid Divider Spacer ScrollView Columns Center AspectRatio | | Typography (11) | Text Heading Code Link Badge Tag Markdown JSON Gradient BigText Digits | | Input (8) | TextInput TextArea PasswordInput NumberInput SearchInput MaskedInput EmailInput PathInput | | Selection (9) | Select MultiSelect RadioGroup Checkbox CheckboxGroup Toggle TreeSelect TagInput ColorPicker | | Data Display (10) | Table DataGrid List VirtualList Tree DirectoryTree KeyValue Definition Card Panel | | Feedback (9) | Spinner ProgressBar ProgressCircle StatusMessage Toast Alert Banner Skeleton MultiProgress | | Navigation (7) | Tabs TabbedContent Breadcrumb Pagination CommandPalette Menu Sidebar | | Overlays (7) | Modal Dialog Drawer Tooltip Popover NotificationCenter NotificationBadge | | Forms (7) | Form FormField Wizard Confirm DatePicker TimePicker FilePicker | | Charts (6) | Sparkline BarChart LineChart PieChart HeatMap Gauge | | Utility (12) | Timer Stopwatch Clock Clipboard KeyboardShortcuts Help ErrorBoundary Log Image QRCode EmbeddedTerminal GitStatus | | Templates (9) | SplashScreen InfoBox AppShell BulletList WelcomeScreen LoginFlow UsageMonitor SetupFlow HelpScreen |

Browse everything: npx termui list or npx termui preview

Library Adapters

TermUI wraps popular CLI libraries so you can use familiar APIs with TermUI theming:

// @clack/prompts-style interactive prompts
import { intro, text, select, spinner } from 'termui/clack';

// picocolors-compatible color API + hex/theme extras
import pc from 'termui/picocolors';
console.log(pc.bold(pc.green('Success!')));

// Non-React imperative prompt API
import { intro, text, confirm, outro } from 'termui/imperative';

// Git status in your TUI
import { useGit } from 'termui/git';

// Styled --help generation
import { createCLI } from 'termui/args';

// AI provider hooks (streaming)
import { useChat, useCompletion } from 'termui/ai';

// chalk-compatible color API with TermUI theme integration
import chalk from 'termui/chalk';

// ora-compatible spinner with TermUI styling
import ora from 'termui/ora';

// meow-compatible CLI argument parser
import meow from 'termui/meow';

// commander-compatible program builder
import { program } from 'termui/commander';

// inquirer-compatible interactive prompts
import { input, confirm, select } from 'termui/inquirer';

Framework Type Bridges

termui/vue and termui/svelte provide framework-agnostic type bridges so TermUI component prop types can be consumed in Vue and Svelte projects without pulling in React:

import type { SpinnerProps, TableProps } from 'termui/vue';
import type { AlertProps, SelectProps } from 'termui/svelte';

CLI

npx termui with no arguments launches a full interactive menu:

| Command | Description | | ------------------------------- | ----------------------------------------- | | npx termui | Interactive menu | | npx termui init | Initialize TermUI in your project | | npx termui add <component> | Add one or more components | | npx termui add --all | Add all 101 components at once | | npx termui update <component> | Re-download a component from the registry | | npx termui list | Browse all available components | | npx termui diff <component> | Show diff vs registry version | | npx termui theme [name] | List or apply a theme | | npx termui preview | Interactive component gallery | | npx termui dev | Watch mode: hot-reload on file change |

Theming

TermUI ships 9 built-in themes.

npx termui theme dracula
npx termui theme nord
npx termui theme catppuccin

| Theme | Description | | --------------- | ------------------------------- | | default | Clean, neutral palette | | dracula | Dark purple with vibrant colors | | nord | Arctic, north-bluish palette | | catppuccin | Soothing pastel mocha tones | | monokai | Classic warm dark theme | | tokyo-night | Vibrant neon city | | one-dark | Atom-inspired dark | | solarized | Ethan Schoonover classic | | high-contrast | Accessibility-focused palette |

Or use a theme programmatically:

import { ThemeProvider, draculaTheme } from '@termui/core';

<ThemeProvider theme={draculaTheme}>
  <App />
</ThemeProvider>;

Custom theme

import { createTheme } from '@termui/core';

const myTheme = createTheme({
  name: 'my-brand',
  colors: {
    primary: '#FF6B6B',
    focusRing: '#FF6B6B',
  },
});

Hooks

import {
  useInput, // keyboard input
  useFocus, // component focus state
  useFocusManager, // programmatic focus
  useTheme, // access theme tokens
  useTerminal, // cols, rows, color depth
  useAnimation, // frame-based animation
  useInterval, // safe setInterval
  useClipboard, // OSC 52 clipboard
  useKeymap, // declarative keybindings
  useMouse, // mouse events
  useResize, // terminal resize
  useAsync, // async data loading
} from '@termui/core';

AI Components

TermUI ships a dedicated set of AI/LLM UI components for building chat interfaces and agent UIs:

| Component | Description | | --------------- | ---------------------------------------------------------------- | | ChatMessage | Renders a single chat turn with role, content, and style | | ChatThread | Scrollable thread of ChatMessage components | | ToolCall | Displays a tool/function call with name and arguments | | ThinkingBlock | Collapsible reasoning/thinking block for chain-of-thought output | | TokenUsage | Shows prompt/completion/total token counts | | ModelSelector | Interactive picker for AI model selection | | FileChange | Diff-style display of file modifications from an agent | | ToolApproval | Confirmation prompt before executing a tool call |

The termui/ai adapter provides streaming React hooks:

import { useChat, useCompletion } from 'termui/ai';

// useChat — multi-turn conversation with streaming
const { messages, input, handleSubmit, isLoading } = useChat({ api: '/api/chat' });

// useCompletion — single-turn streaming text completion
const { completion, complete, isLoading } = useCompletion({ api: '/api/complete' });

Testing

@termui/testing provides headless testing utilities for TermUI components:

import { renderToString, screen, waitFor, fireEvent } from '@termui/testing';

const output = await renderToString(<Spinner style="dots" />);
expect(screen.hasText('⠋', output)).toBe(true);

| Export | Description | | -------------------- | ------------------------------------------------------- | | renderToString | Render a component to a plain string (one frame) | | createTestRenderer | Reusable renderer with render / cleanup | | screen | Query helpers: getByText, hasText, getLines, etc. | | fireEvent | Simulate keyboard input: key, type, press | | waitFor | Poll an assertion until it passes or times out |

Documentation

In-repo docs live under docs/. Start at docs/index.md for the overview and category guides (layout, typography, feedback, charts, and more). API-focused pages:

| Doc | Contents | | -------------------------------------------- | ----------------- | | docs/api/cli.md | CLI reference | | docs/api/hooks.md | Hooks API | | docs/api/testing.md | Testing utilities | | docs/adapters.md | Adapters overview |

Stack

| Layer | Technology | | ------------ | --------------------------------------------------------------- | | Language | TypeScript (ESM-only) | | Renderer | Ink (React for terminal) | | Layout | Yoga (Facebook's flexbox engine) | | Distribution | shadcn/ui-style CLI | | Runtime | Node.js 18+ |

Monorepo Structure

termui/
├── packages/
│   ├── core/          # Terminal layer, styling engine, 12 hooks
│   ├── components/    # 101 UI components (including AI components)
│   ├── testing/       # Headless testing utilities
│   ├── adapters/      # Drop-in adapters (clack, chalk, ora, meow, commander, inquirer, vue, svelte…)
│   ├── types/         # Framework-agnostic TypeScript type definitions (@termui/types)
│   └── cli/           # npx termui CLI tool
├── registry/          # Component registry (schema + meta)
├── templates/         # Starter app templates
├── examples/
│   ├── demo/          # Interactive demo app
│   └── ai-demo/       # AI chat interface demo
└── .github/
    ├── assets/        # README images and media
    └── workflows/     # CI (Node 18, 20, 22)

Development

This repository is a pnpm workspace with Turborepo. Use the same toolchain CI uses so local results match the checks on a PR.

Prerequisites

| Requirement | Notes | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Node.js | 18+ (CI runs 18, 20, and 22) | | pnpm | 9.x — this repo pins packageManager in package.json. Enable with Corepack: corepack enable then corepack prepare [email protected] --activate (or match the version in package.json). |

Do not use npm or yarn at the repo root; workspace protocol and scripts expect pnpm.

First-time setup

git clone https://github.com/Arindam200/termui.git
cd termui
pnpm install

# Build core first — other packages depend on it
pnpm --filter @termui/core build

pnpm test

Full fork-and-PR workflow, commit conventions, and component checklist: CONTRIBUTING.md. For registry and component structure: CONTRIBUTING_COMPONENTS.md.

Common commands

# Tests (all packages)
pnpm test

# Type-check
pnpm typecheck

# Build everything
pnpm build

# Format & lint
pnpm format
pnpm lint

# Interactive demo app
pnpm --filter @termui/demo start

# AI demo (examples/ai-demo)
pnpm --filter @termui/ai-demo start

# Dev: parallel package watch (Turborepo)
pnpm dev

# CLI package only — run from repo root
pnpm --filter @termui/cli dev

Troubleshooting

| Problem | What to try | | ------------------------------------ | ------------------------------------------------------------------------------------------ | | Build or test fails after git pull | pnpm install, then pnpm --filter @termui/core build, then pnpm build or pnpm test. | | Wrong package manager errors | Use pnpm from the repo root, not npm/yarn. | | Stale Turborepo cache | pnpm exec turbo run build --force (or your usual clean build). | | Type errors across packages | Run pnpm typecheck after a full pnpm build. |

Roadmap

| Phase | Status | Description | | ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------ | | Phase 1 | ✅ Done | 19 components, CLI (init/add/list), 3 themes, 12 hooks | | Phase 2 | ✅ Done | 75 components, 9 themes, adapters, diff/update/theme commands | | Phase 3 | ✅ Done | 101 components, charts, dev tools, templates, testing package | | Phase 4 | 🚧 In Progress | AI components, streaming hooks, chalk/ora/meow/commander/inquirer/Vue/Svelte adapters, @termui/types, 600+ tests | | Phase 5 | 🔜 Planned | Plugin system, community registry |

Community & contributing

• CONTRIBUTING.md — setup, workflow, tests, commits, PRs, reporting issues.
• CONTRIBUTING_COMPONENTS.md — adding or changing components and registry entries.
• GOVERNANCE.md — project governance.
• Issues — bugs and feature requests.

License

MIT © Arindam Majumder