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 — Full component and prop reference
• hooks.md — Hook API details and custom hook patterns
• 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)