Ink — React for interactive command-line apps.

SKILL.md

---
name: ink-tui
description: Ink — React for interactive command-line apps. Build rich terminal UIs with React components. 
---

# Ink Skill Guide

## Overview

Ink renders React components directly to the terminal using Yoga layout (Flexbox for CLI). It handles diffing, re-rendering, and terminal I/O. Components receive real React state, effects, and hooks — the same mental model as web React.Requires Node.js 22+ and React 19.2+ as peer dependencies.

## Triggers

when the user wants to create CLI/TUI apps, terminal dashboards, interactive prompts, colored terminal output, spinners, progress bars, or tables using JSX/React syntax. 
 
- building CLI apps with React
- creating interactive terminal UIs
- rendering styled terminal output
- handling keyboard input in the terminal
- terminal layout with Flexbox/Yoga

## Quick Start

```bash
mkdir my-cli && cd my-cli
pnpm init
pnpm add ink react @types/react
pnpm add -D tsx typescript @types/node
```

```json
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "outDir": "build"
  }
}
```

```tsx
// index.tsx
import { render, Box, Text } from 'ink';

const App = () => (
  <Box flexDirection="column">
    <Text color="green" bold>Hello, CLI!</Text>
  </Box>
);

render(<App />);
```

Run: `node --import=tsx index.tsx`

## Architecture

Ink uses `react-reconciler` as its rendering core and `yoga-layout` as its layout engine. It mounts components into a virtual terminal, diffs against current output, and writes changes to stdout. This means:
- Full React state/lifecycle (useState, useEffect, etc.)
- Flexbox layout via Yoga (not CSS — uses integer-based positioning)
- Terminal output is treated as an append-only buffer that gets replaced on re-render

## Components

### `<Box>` — Layout Container

```tsx
import { Box, Text } from 'ink';

// Row layout (default flexDirection)
<Box gap={2}>
  <Text>Left</Text>
  <Text>Right</Text>
</Box>

// Column layout with border
<Box flexDirection="column" borderStyle="round" padding={1} width={40}>
  <Text bold>Title</Text>
  <Text dim>subtitle</Text>
</Box>
```

Key Box props: `width`, `height`, `padding`/`paddingX`/`paddingY`, `borderStyle` (single/double/round/classic/bold), `borderDimColor`, `gap`, `flexGrow`, `flexShrink`, `flexDirection` (row/column), `justifyContent`, `alignItems`.

### `<Text>` — Styled Text

```tsx
// Direct styling
<Text color="green" bold underline>Success</Text>

// Nested spans
<Text>
  Regular <Text bold>bold</Text> and <Text color="red" inverse>inverse red</Text>
</Text>

// Wrap via width
<Text width={40} wrap="truncate">Truncated long text...</Text>
```

Colors: black/red/green/yellow/blue/magenta/cyan/white/gray + Bright variants (redBright, etc.), hex (#ff0000), rgb(255,0,0).  
Background: prefix with `bg` (bgGreen, bgCyanBright).  
Styles: bold, dim, italic, underline, strikethrough, inverse.

### `<Newline>`, `<Spacer>`

```tsx
<Newline count={2} />       // n blank lines
<Spacer />                   // flex spacer
<Spacer height={3} />        // fixed height spacer
```

## Hooks

### `useInput` — Keyboard Input

```tsx
import { useInput } from 'ink';

useInput((input, key) => {
  if (key.escape || input === 'q') exit();           // exit on Escape or 'q'
  if (key.upArrow) navigateUp();
  if (key.downArrow) navigateDown();
  if (key.return) selectItem();
});
```

key object: upArrow, downArrow, leftArrow, rightArrow, return, escape, tab, backspace, delete, ctrl, shift, meta, space, pageUp, pageDown, home, end, f1–f12.

### `useApp` — App-Level Control

```tsx
import { useApp } from 'ink';
const { exit } = useApp();
exit();  // or exit(error)
```

### `useFocus` — Focus Management

```tsx
import { useFocus } from 'ink';
const { isFocused } = useFocus({ autoFocus: true });
// Style differently when focused
<Text color={isFocused ? 'blue' : 'dim'}>{label}</Text>
```

### `useStdin` / `useStdout` — Stream Access

```tsx
const { stdin, isRawModeSupported } = useStdin();
const { stdout } = useStdout();
```

## render() Options

```tsx
render(<App />, {
  exitOnCtrlC: true,         // default true
  debug: false,              // show Yoga layout debug
  patchConsole: true,        // suppress console output
});
```

## Common Patterns

### Select/Menu

```tsx
const Menu = ({ items, onSelect }) => {
  const [idx, setIdx] = useState(0);
  useInput((_, key) => {
    if (key.upArrow) setIdx(i => Math.max(0, i - 1));
    if (key.downArrow) setIdx(i => Math.min(items.length - 1, i + 1));
    if (key.return) onSelect(items[idx]);
  });
  return (
    <Box flexDirection="column">
      {items.map((item, i) => (
        <Text key={i} color={i === idx ? 'green' : undefined}>
          {i === idx ? '❯ ' : '  '}{item}
        </Text>
      ))}
    </Box>
  );
};
```

### Spinner (useEffect + setInterval)

```tsx
const Spinner = () => {
  const [frame, setFrame] = useState(0);
  const chars = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
  useEffect(() => {
    const id = setInterval(() => setFrame(f => (f + 1) % chars.length), 80);
    return () => clearInterval(id);
  }, []);
  return <Text>{chars[frame]} Loading...</Text>;
};
```

### Progress Bar

```tsx
const ProgressBar = ({ percent }) => {
  const filled = '█'.repeat(Math.round(percent / 5));
  const empty = '░'.repeat(20 - filled.length);
  return <Text>{filled}{empty} {percent}%</Text>;
};
```

### Input Field (useInput + useState)

```tsx
const Input = ({ onSubmit }) => {
  const [value, setValue] = useState('');
  useInput((input, key) => {
    if (key.return) { onSubmit(value); setValue(''); }
    else if (key.backspace) setValue(v => v.slice(0, -1));
    else if (input.length === 1 && !key.ctrl) setValue(v => v + input);
  });
  return <Text>❯ {value}<Text dim>█</Text></Text>;
};
```

## Resources

This skill includes:
- **[components.md](references/components.md)** — Full component and prop reference
- **[hooks.md](references/hooks.md)** — Hook API details and custom hook patterns
- **[examples.md](references/examples.md)** — Complete runnable examples (counter, table, loading, CLI arguments)

## Key Constraints

- **Node.js >= 22** required (ESM only)
- **React >= 19.2** is a peer dependency
- Only works in real terminal (no browser)
- Layout via Yoga Flexbox — units are characters/rows, not pixels
- No scrolling — the terminal viewport is the canvas
- Colors depend on terminal support (most modern terminals support 256-color)
- Interactive mode requires raw stdin (Ink enables it automatically)