Overview
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 the 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
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)
Prerequisites
- Node >= 20
- React >= 19
- Ink v6+ is ESM-only (
"type": "module" in package.json)
- Windows host is primary (PowerShell). Commands provided are compatible with PowerShell unless noted.
Procedure
Install Ink and React
npm install ink react
Or scaffold a full project:
npx create-ink-app my-cli
npx create-ink-app my-cli --typescript
Create a 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 />);
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(() => {
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>
);
}
Pitfalls
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 text, Ink enforces that only <Text> components hold text content. Always wrap strings in <Text>.
useInput does nothing without raw mode on stdin - If stdin is not in raw mode (e.g., piped input in CI, non-TTY environments), useInput never fires. Check useStdin().isRawModeSupported before relying on keyboard input, and provide a non-interactive fallback for CI/piped contexts.
Ink v6 is ESM-only and breaks CommonJS imports - Importing Ink with require('ink') throws require() of ES Module. You must use import syntax and set "type": "module" in your package.json. This also means Ink v6 cannot be used in projects that are stuck on CommonJS without a build step.
<Static> items must have stable keys or they re-render - The <Static> component renders each item exactly once and never updates it. If you pass items without stable key props or if you mutate the items array in place instead of appending, previously rendered lines can disappear or duplicate.
The app stays alive as long as stdin listeners or timers exist - Ink's render() keeps the process running while there are pending timers, promises, or stdin listeners. Forgetting to call clearInterval, clearTimeout, or exit() from useApp() results in a CLI tool that hangs after the work is done.
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.
Verification
- Check Node version:
node -v (must be >= 20)
- Check package.json for
"type": "module" if using Ink v6+
- Run the CLI app:
node dist/index.js or npm start
- Verify interactive input works in a real terminal (not piped)
- Verify the process exits cleanly after completion (no hanging)
- Verify no raw text is placed directly inside
<Box> components
UI/UX 2026 Guidelines
This skill also covers interface design, UX review, accessibility, responsive layouts, design systems, mobile/web UI, component behavior, interaction states, visual hierarchy, usability improvements, and frontend implementation guidance.
Workflow:
- Start from the user task and information architecture, not decoration.
- Map key states: empty, loading, success, error, disabled, permission-limited, offline, and responsive variants.
- Apply accessibility requirements early: keyboard flow, focus visibility, labels, contrast, reduced motion, touch targets, text resizing, and semantic structure.
- Use design-system primitives where available; otherwise define tokens for spacing, color, type, elevation, radius, and motion.
- Design responsive layouts with stable dimensions and no text overlap across desktop and mobile.
- Validate with realistic content, long labels, error text, and touch/keyboard interaction.
- Deliver concrete implementation guidance, not vague aesthetic notes.
Quality Checklist:
- User can complete the core task quickly and repeatedly.
- UI supports keyboard, screen readers, visible focus, and sufficient contrast.
- Mobile and desktop layouts do not overlap or rely on fragile viewport-scaled text.
- Controls use familiar affordances and expose state clearly.
- Motion is purposeful and respects reduced-motion preferences.
- Visual direction is intentional and consistent with the product domain.
Failure Handling:
If requirements conflict, prioritize usability, accessibility, and product fit over novelty. If a requested visual pattern harms readability or accessibility, explain the tradeoff and offer a better variant. Verify current platform guidance when building for Apple, Android, or a specific design system.
Current References:
References
This skill does not ship a companion pack. Box/Text/hooks usage is in Procedure above. Full props, community components, and example apps:
Related skills
- frontend-developer: For general React web or React Native development.
- shell-scripting: For simple shell scripts that just print output.
1---
2name: react-ink
3description: "Builds interactive terminal UIs with React Ink: Box and Text, Yoga flexbox, useInput, useFocus, Static logs, and create-ink-app. Use when the user wants a React CLI, Ink components, or styled stdout UI. Not for React DOM, Next.js, or React Native screens. Do not use for shell scripts that only print text."
4version: 1.0.1
5metadata:
6 source: https://skillmd.com/skills/kayforkind/react-ink
7---
8
9## Overview
10
11React 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 the 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.
12
13## When to Use
14
15Trigger this skill when the user:
16- Wants to build an interactive CLI application using React
17- Needs terminal UI components with Flexbox layout (Box, Text)
18- Is handling keyboard input in a terminal app with `useInput`
19- Wants focus management across terminal UI elements
20- Needs to display progress, spinners, or streaming logs in a CLI
21- Is scaffolding a new CLI project with `create-ink-app`
22- Wants to render styled text with colors, borders, or formatting in the terminal
23
24Do NOT trigger this skill for:
25- General React web or React Native development (use frontend-developer)
26- Simple shell scripts that just print output (use shell-scripting)
27
28## Prerequisites
29
30- Node >= 20
31- React >= 19
32- Ink v6+ is ESM-only (`"type": "module"` in package.json)
33- Windows host is primary (PowerShell). Commands provided are compatible with PowerShell unless noted.
34
35## Procedure
36
371. **Install Ink and React**
38 ```bash
39 npm install ink react
40 ```
41 Or scaffold a full project:
42 ```bash
43 npx create-ink-app my-cli
44 npx create-ink-app my-cli --typescript
45 ```
46
472. **Create a basic app**
48 ```tsx
49 import React, {useState, useEffect} from 'react';
50 import {render, Text} from 'ink';
51
52 function Counter() {
53 const [count, setCount] = useState(0);
54
55 useEffect(() => {
56 const timer = setInterval(() => {
57 setCount(prev => prev + 1);
58 }, 100);
59 return () => clearInterval(timer);
60 }, []);
61
62 return <Text color="green">{count} tests passed</Text>;
63 }
64
65 render(<Counter />);
66 ```
67
683. **Render an app and handle exit**
69 ```tsx
70 import {render, useApp, useInput, Text} from 'ink';
71
72 function App() {
73 const {exit} = useApp();
74 useInput((input, key) => {
75 if (input === 'q') exit();
76 });
77 return <Text>Press q to quit</Text>;
78 }
79
80 const instance = render(<App />);
81 await instance.waitUntilExit();
82 console.log('Goodbye!');
83 ```
84
854. **Build a layout with Box**
86 ```tsx
87 import {Box, Text} from 'ink';
88
89 function Dashboard() {
90 return (
91 <Box flexDirection="column" padding={1}>
92 <Box borderStyle="round" borderColor="blue" paddingX={1}>
93 <Text bold>Header</Text>
94 </Box>
95 <Box gap={2}>
96 <Box flexDirection="column" width="50%">
97 <Text color="green">Left panel</Text>
98 </Box>
99 <Box flexDirection="column" width="50%">
100 <Text color="yellow">Right panel</Text>
101 </Box>
102 </Box>
103 </Box>
104 );
105 }
106 ```
107
1085. **Handle keyboard input**
109 ```tsx
110 import {useState} from 'react';
111 import {useInput, Text, Box} from 'ink';
112
113 function Movement() {
114 const [x, setX] = useState(0);
115 const [y, setY] = useState(0);
116
117 useInput((_input, key) => {
118 if (key.leftArrow) setX(prev => Math.max(0, prev - 1));
119 if (key.rightArrow) setX(prev => Math.min(20, prev + 1));
120 if (key.upArrow) setY(prev => Math.max(0, prev - 1));
121 if (key.downArrow) setY(prev => Math.min(10, prev + 1));
122 });
123
124 return (
125 <Box flexDirection="column">
126 <Text>Position: {x}, {y}</Text>
127 <Text>Use arrow keys to move</Text>
128 </Box>
129 );
130 }
131 ```
132
1336. **Build a focusable selection list**
134 ```tsx
135 import {Box, Text, useFocus} from 'ink';
136
137 function Item({label}: {label: string}) {
138 const {isFocused} = useFocus();
139 return (
140 <Text color={isFocused ? 'blue' : undefined}>
141 {isFocused ? '>' : ' '} {label}
142 </Text>
143 );
144 }
145
146 function SelectList() {
147 return (
148 <Box flexDirection="column">
149 <Item label="Option A" />
150 <Item label="Option B" />
151 <Item label="Option C" />
152 </Box>
153 );
154 }
155 ```
156 Tab and Shift+Tab cycle focus. Use `useFocusManager().focus(id)` for programmatic control.
157
1587. **Display streaming logs with Static**
159 ```tsx
160 import {useState, useEffect} from 'react';
161 import {render, Static, Box, Text} from 'ink';
162
163 function BuildOutput() {
164 const [logs, setLogs] = useState<string[]>([]);
165 const [current, setCurrent] = useState('Starting...');
166
167 useEffect(() => {
168 const timer = setInterval(() => {
169 setLogs(prev => [...prev, current]);
170 setCurrent(`Building step ${prev.length + 1}...`);
171 }, 500);
172 return () => clearInterval(timer);
173 }, []);
174
175 return (
176 <Box flexDirection="column">
177 <Static items={logs}>
178 {(log, i) => <Text key={i} color="green"> {log}</Text>}
179 </Static>
180 <Text color="yellow"> {current}</Text>
181 </Box>
182 );
183 }
184 ```
185
1868. **Use Suspense for async data**
187 ```tsx
188 import React, {Suspense} from 'react';
189 import {render, Text} from 'ink';
190
191 let data: string | undefined;
192 let promise: Promise<void> | undefined;
193
194 function fetchData() {
195 if (data) return data;
196 if (!promise) {
197 promise = new Promise(resolve => {
198 setTimeout(() => { data = 'Loaded!'; resolve(); }, 1000);
199 });
200 }
201 throw promise;
202 }
203
204 function DataView() {
205 const result = fetchData();
206 return <Text color="green">{result}</Text>;
207 }
208
209 render(
210 <Suspense fallback={<Text color="yellow">Loading...</Text>}>
211 <DataView />
212 </Suspense>
213 );
214 ```
215
2169. **Respond to terminal resize**
217 ```tsx
218 import {useWindowSize, Box, Text} from 'ink';
219
220 function ResponsiveLayout() {
221 const {columns, rows} = useWindowSize();
222 return (
223 <Box flexDirection="column">
224 <Text>Terminal: {columns}x{rows}</Text>
225 <Box width={columns > 80 ? '50%' : '100%'}>
226 <Text>Content adapts to terminal size</Text>
227 </Box>
228 </Box>
229 );
230 }
231 ```
232
233## Pitfalls
234
2351. **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 text, Ink enforces that only `<Text>` components hold text content. Always wrap strings in `<Text>`.
236
2372. **`useInput` does nothing without raw mode on stdin** - If stdin is not in raw mode (e.g., piped input in CI, non-TTY environments), `useInput` never fires. Check `useStdin().isRawModeSupported` before relying on keyboard input, and provide a non-interactive fallback for CI/piped contexts.
238
2393. **Ink v6 is ESM-only and breaks CommonJS imports** - Importing Ink with `require('ink')` throws `require() of ES Module`. You must use `import` syntax and set `"type": "module"` in your `package.json`. This also means Ink v6 cannot be used in projects that are stuck on CommonJS without a build step.
240
2414. **`<Static>` items must have stable keys or they re-render** - The `<Static>` component renders each item exactly once and never updates it. If you pass items without stable `key` props or if you mutate the items array in place instead of appending, previously rendered lines can disappear or duplicate.
242
2435. **The app stays alive as long as stdin listeners or timers exist** - Ink's `render()` keeps the process running while there are pending timers, promises, or stdin listeners. Forgetting to call `clearInterval`, `clearTimeout`, or `exit()` from `useApp()` results in a CLI tool that hangs after the work is done.
244
2456. **`stdin.setRawMode is not a function`** - Running in non-TTY environment (piped input, CI). Check `isRawModeSupported` from `useStdin()` before enabling.
246
2477. **`React is not defined`** - Missing React import with JSX transform. Add `import React from 'react'` or configure JSX automatic runtime.
248
249## Verification
250
2511. Check Node version: `node -v` (must be >= 20)
2522. Check package.json for `"type": "module"` if using Ink v6+
2533. Run the CLI app: `node dist/index.js` or `npm start`
2544. Verify interactive input works in a real terminal (not piped)
2555. Verify the process exits cleanly after completion (no hanging)
2566. Verify no raw text is placed directly inside `<Box>` components
257
258## UI/UX 2026 Guidelines
259
260This skill also covers interface design, UX review, accessibility, responsive layouts, design systems, mobile/web UI, component behavior, interaction states, visual hierarchy, usability improvements, and frontend implementation guidance.
261
262**Workflow:**
2631. Start from the user task and information architecture, not decoration.
2642. Map key states: empty, loading, success, error, disabled, permission-limited, offline, and responsive variants.
2653. Apply accessibility requirements early: keyboard flow, focus visibility, labels, contrast, reduced motion, touch targets, text resizing, and semantic structure.
2664. Use design-system primitives where available; otherwise define tokens for spacing, color, type, elevation, radius, and motion.
2675. Design responsive layouts with stable dimensions and no text overlap across desktop and mobile.
2686. Validate with realistic content, long labels, error text, and touch/keyboard interaction.
2697. Deliver concrete implementation guidance, not vague aesthetic notes.
270
271**Quality Checklist:**
272- User can complete the core task quickly and repeatedly.
273- UI supports keyboard, screen readers, visible focus, and sufficient contrast.
274- Mobile and desktop layouts do not overlap or rely on fragile viewport-scaled text.
275- Controls use familiar affordances and expose state clearly.
276- Motion is purposeful and respects reduced-motion preferences.
277- Visual direction is intentional and consistent with the product domain.
278
279**Failure Handling:**
280If requirements conflict, prioritize usability, accessibility, and product fit over novelty. If a requested visual pattern harms readability or accessibility, explain the tradeoff and offer a better variant. Verify current platform guidance when building for Apple, Android, or a specific design system.
281
282**Current References:**
283- W3C WCAG 2.2: https://www.w3.org/TR/WCAG22/
284- W3C Understanding WCAG 2.2: https://www.w3.org/WAI/WCAG22/Understanding/intro
285- Apple Human Interface Guidelines: https://developer.apple.com/design/human-interface-guidelines
286- Material accessibility guidance: https://m2.material.io/design/usability/accessibility.html
287
288## References
289
290This skill does not ship a companion pack. Box/Text/hooks usage is in Procedure above. Full props, community components, and example apps:
291
292- Ink README (components + hooks): https://github.com/vadimdemedes/ink
293- Examples: https://github.com/vadimdemedes/ink/tree/master/examples
294
295## Related skills
296
297- frontend-developer: For general React web or React Native development.
298- shell-scripting: For simple shell scripts that just print output.