react-ink

When this skill is activated, always start your first response with the 🧢 emoji.

React Ink

React Ink brings React's component model to the terminal. Instead of rendering to the DOM, Ink renders to stdout using a custom React reconciler backed by Yoga layout engine (the same Flexbox implementation used by React Native). Build interactive CLI tools with components like <Box> for layout and <Text> for styled output, handle keyboard input with useInput, and manage focus with useFocus - all using familiar React patterns including hooks, state, effects, Suspense, and concurrent rendering.

When to use this skill

Trigger this skill when the user:

• Wants to build an interactive CLI application using React
• Needs terminal UI components with Flexbox layout (Box, Text)
• Is handling keyboard input in a terminal app with useInput
• Wants focus management across terminal UI elements
• Needs to display progress, spinners, or streaming logs in a CLI
• Is scaffolding a new CLI project with create-ink-app
• Wants to render styled text with colors, borders, or formatting in the terminal

Do NOT trigger this skill for:

• General React web or React Native development (use frontend-developer)
• Simple shell scripts that just print output (use shell-scripting)

Setup & authentication

Installation

npm install ink react

Or scaffold a full project:

npx create-ink-app my-cli
npx create-ink-app my-cli --typescript

Requirements: Node >= 20, React >= 19. Ink v6+ is ESM-only ("type": "module" in package.json).

Basic app

import React, {useState, useEffect} from 'react';
import {render, Text} from 'ink';

function Counter() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const timer = setInterval(() => {
      setCount(prev => prev + 1);
    }, 100);
    return () => clearInterval(timer);
  }, []);

  return <Text color="green">{count} tests passed</Text>;
}

render(<Counter />);

Core concepts

Component model: <Box> is a Flexbox container (like div with display: flex). <Text> renders styled text. Only <Text> and string literals can contain text content - never put raw text inside <Box> directly.

Layout engine: Ink uses Yoga (same as React Native) for Flexbox layout. Box supports flexDirection, justifyContent, alignItems, gap, padding, margin, borders, and absolute positioning.

Input handling: useInput captures keyboard events. It receives (input, key) where input is the character pressed and key has boolean flags like leftArrow, return, escape, ctrl. Requires raw mode on stdin.

Focus system: useFocus marks components as focusable. Tab/Shift+Tab cycles focus. useFocusManager provides programmatic control. Focus state drives visual highlighting.

Static output: <Static> renders items that persist above the dynamic area - perfect for completed log lines, test results, or build output that shouldn't be cleared on re-render.

Render lifecycle: render() returns {rerender, unmount, waitUntilExit, clear, cleanup}. The app stays alive while there are pending timers, promises, or stdin listeners. Exit via useApp().exit() or Ctrl+C.

Common tasks

Render an app and handle exit

import {render, useApp, useInput, Text} from 'ink';

function App() {
  const {exit} = useApp();
  useInput((input, key) => {
    if (input === 'q') exit();
  });
  return <Text>Press q to quit</Text>;
}

const instance = render(<App />);
await instance.waitUntilExit();
console.log('Goodbye!');

Build a layout with Box

import {Box, Text} from 'ink';

function Dashboard() {
  return (
    <Box flexDirection="column" padding={1}>
      <Box borderStyle="round" borderColor="blue" paddingX={1}>
        <Text bold>Header</Text>
      </Box>
      <Box gap={2}>
        <Box flexDirection="column" width="50%">
          <Text color="green">Left panel</Text>
        </Box>
        <Box flexDirection="column" width="50%">
          <Text color="yellow">Right panel</Text>
        </Box>
      </Box>
    </Box>
  );
}

Handle keyboard input

import {useState} from 'react';
import {useInput, Text, Box} from 'ink';

function Movement() {
  const [x, setX] = useState(0);
  const [y, setY] = useState(0);

  useInput((_input, key) => {
    if (key.leftArrow) setX(prev => Math.max(0, prev - 1));
    if (key.rightArrow) setX(prev => Math.min(20, prev + 1));
    if (key.upArrow) setY(prev => Math.max(0, prev - 1));
    if (key.downArrow) setY(prev => Math.min(10, prev + 1));
  });

  return (
    <Box flexDirection="column">
      <Text>Position: {x}, {y}</Text>
      <Text>Use arrow keys to move</Text>
    </Box>
  );
}

Build a focusable selection list

import {Box, Text, useFocus} from 'ink';

function Item({label}: {label: string}) {
  const {isFocused} = useFocus();
  return (
    <Text color={isFocused ? 'blue' : undefined}>
      {isFocused ? '>' : ' '} {label}
    </Text>
  );
}

function SelectList() {
  return (
    <Box flexDirection="column">
      <Item label="Option A" />
      <Item label="Option B" />
      <Item label="Option C" />
    </Box>
  );
}

Tab and Shift+Tab cycle focus. Use useFocusManager().focus(id) for programmatic control.

Display streaming logs with Static

import {useState, useEffect} from 'react';
import {render, Static, Box, Text} from 'ink';

function BuildOutput() {
  const [logs, setLogs] = useState<string[]>([]);
  const [current, setCurrent] = useState('Starting...');

  useEffect(() => {
    // Add completed logs and update current status
    const timer = setInterval(() => {
      setLogs(prev => [...prev, current]);
      setCurrent(`Building step ${prev.length + 1}...`);
    }, 500);
    return () => clearInterval(timer);
  }, []);

  return (
    <Box flexDirection="column">
      <Static items={logs}>
        {(log, i) => <Text key={i} color="green">✓ {log}</Text>}
      </Static>
      <Text color="yellow">⟳ {current}</Text>
    </Box>
  );
}

Use Suspense for async data

import React, {Suspense} from 'react';
import {render, Text} from 'ink';

let data: string | undefined;
let promise: Promise<void> | undefined;

function fetchData() {
  if (data) return data;
  if (!promise) {
    promise = new Promise(resolve => {
      setTimeout(() => { data = 'Loaded!'; resolve(); }, 1000);
    });
  }
  throw promise;
}

function DataView() {
  const result = fetchData();
  return <Text color="green">{result}</Text>;
}

render(
  <Suspense fallback={<Text color="yellow">Loading...</Text>}>
    <DataView />
  </Suspense>
);

Respond to terminal resize

import {useWindowSize, Box, Text} from 'ink';

function ResponsiveLayout() {
  const {columns, rows} = useWindowSize();
  return (
    <Box flexDirection="column">
      <Text>Terminal: {columns}x{rows}</Text>
      <Box width={columns > 80 ? '50%' : '100%'}>
        <Text>Content adapts to terminal size</Text>
      </Box>
    </Box>
  );
}

Error handling

| Error | Cause | Resolution | |---|---|---| | Text content inside <Box> | Raw text placed directly in Box | Wrap all text in <Text> components | | stdin.setRawMode is not a function | Running in non-TTY environment (piped input, CI) | Check isRawModeSupported from useStdin() before enabling | | React is not defined | Missing React import with JSX transform | Add import React from 'react' or configure JSX automatic runtime | | Node version error | Ink v6 requires Node >= 20 | Upgrade Node or use Ink v5 for older Node | | require() of ES Module | Importing Ink with CommonJS | Ink v6 is ESM-only - use import syntax and "type": "module" |

Gotchas

1. Raw text inside <Box> silently breaks rendering - Placing a string directly inside <Box> without wrapping it in <Text> causes a runtime error. Unlike web React where a <div> can contain bare