`).
```tsx
import {Box, Text} from 'ink';
// Basic layout
Row 1
Row 2
// With border
Bordered content
// Flex alignment
Left
Right
```
Key properties:
- **Dimensions**: `width`, `height`, `minWidth`, `minHeight`
- **Padding**: `padding`, `paddingX`, `paddingY`, `paddingTop`, etc.
- **Margin**: `margin`, `marginX`, `marginY`, `marginTop`, etc.
- **Flex**: `flexDirection`, `flexGrow`, `flexShrink`, `flexWrap`, `alignItems`, `justifyContent`
- **Borders**: `borderStyle` (`single`, `double`, `round`, `bold`, `classic`), `borderColor`
- **Background**: `backgroundColor`
- **Gap**: `gap`, `columnGap`, `rowGap`
For full property reference, see [references/components.md](references/components.md).
### Newline & Spacer
```tsx
import {Text, Newline, Spacer, Box} from 'ink';
// Newline inside Text
Line 1Line 2Line 4
// Spacer fills available space
Left
Right
```
### Static
Render permanent output above the dynamic UI (logs, completed tasks).
```tsx
import {Static, Box, Text} from 'ink';
const App = ({completedTasks}) => (
<>
{task => (
✔ {task.title}
)}
Processing...
);
```
### Transform
Transform rendered text output.
```tsx
import {Transform, Text} from 'ink';
output.toUpperCase()}>
hello world
// Output: HELLO WORLD
```
---
## Essential Hooks
### useInput
Handle keyboard input.
```tsx
import {useInput, useApp} from 'ink';
const App = () => {
const {exit} = useApp();
useInput((input, key) => {
if (input === 'q') exit();
if (key.upArrow) { /* move up */ }
if (key.downArrow) { /* move down */ }
if (key.return) { /* select */ }
if (key.escape) { /* cancel */ }
});
return
Press q to quit, arrows to navigate;
};
```
Key properties: `leftArrow`, `rightArrow`, `upArrow`, `downArrow`, `return`, `escape`, `ctrl`, `shift`, `tab`, `backspace`, `delete`, `pageUp`, `pageDown`, `meta`.
Disable input capture: `useInput(handler, {isActive: false})`.
### useApp
Control app lifecycle.
```tsx
import {useApp} from 'ink';
const App = () => {
const {exit} = useApp();
// Exit after 5 seconds
useEffect(() => {
setTimeout(() => exit(), 5000);
}, []);
return
Exiting soon...;
};
```
### useFocus & useFocusManager
Manage focus between components.
```tsx
import {useFocus, Box, Text} from 'ink';
const FocusableItem = ({label}) => {
const {isFocused} = useFocus();
return (
{isFocused ? '>' : ' '} {label}
);
};
// Tab cycles focus, Shift+Tab goes backwards
```
Focus options: `autoFocus`, `isActive`, `id`.
For complete hooks reference, see [references/hooks.md](references/hooks.md).
---
## Common Patterns
### Interactive List
```tsx
import React, {useState} from 'react';
import {render, Box, Text, useInput, useApp} from 'ink';
const items = ['Option A', 'Option B', 'Option C'];
const SelectList = () => {
const [selected, setSelected] = useState(0);
const {exit} = useApp();
useInput((input, key) => {
if (key.upArrow) setSelected(s => Math.max(0, s - 1));
if (key.downArrow) setSelected(s => Math.min(items.length - 1, s + 1));
if (key.return) {
console.log(`Selected: ${items[selected]}`);
exit();
}
if (input === 'q') exit();
});
return (
{items.map((item, i) => (
{i === selected ? '>' : ' '} {item}
))}
);
};
render(
);
```
### Progress Indicator
```tsx
import React, {useState, useEffect} from 'react';
import {render, Box, Text} from 'ink';
const ProgressBar = ({percent}) => {
const width = 20;
const filled = Math.round(width * percent / 100);
return (
[
{'█'.repeat(filled)}
{'░'.repeat(width - filled)}
] {percent}%
);
};
const App = () => {
const [progress, setProgress] = useState(0);
useEffect(() => {
const timer = setInterval(() => {
setProgress(p => p >= 100 ? 100 : p + 10);
}, 200);
return () => clearInterval(timer);
}, []);
return
;
};
render(
);
```
### Task List with Static Output
```tsx
import React, {useState, useEffect} from 'react';
import {render, Static, Box, Text} from 'ink';
const App = () => {
const [completed, setCompleted] = useState([]);
const [current, setCurrent] = useState('Task 1');
useEffect(() => {
const tasks = ['Task 1', 'Task 2', 'Task 3'];
let i = 0;
const timer = setInterval(() => {
if (i < tasks.length) {
setCompleted(prev => [...prev, {id: i, title: tasks[i]}]);
i++;
setCurrent(tasks[i] || 'Done!');
}
}, 1000);
return () => clearInterval(timer);
}, []);
return (
<>
{task => (
✔ {task.title}
)}
⏳ {current}
);
};
render(
);
```
---
## Render API
```tsx
import {render} from 'ink';
const {rerender, unmount, waitUntilExit, clear} = render(
);
// Update props
rerender(
);
// Programmatic exit
unmount();
// Wait for exit
await waitUntilExit();
// Clear output
clear();
```
Options:
```tsx
render(
, {
stdout: process.stdout,
stdin: process.stdin,
stderr: process.stderr,
exitOnCtrlC: true,
patchConsole: true,
debug: false,
maxFps: 30,
});
```
---
## Testing
Use `ink-testing-library`:
```tsx
import {render} from 'ink-testing-library';
import {Text} from 'ink';
const {lastFrame} = render(
Hello);
expect(lastFrame()).toBe('Hello');
```
---
## Useful Third-Party Components
| Package | Purpose |
|---------|---------|
| `ink-text-input` | Text input field |
| `ink-spinner` | Loading spinners |
| `ink-select-input` | Select/dropdown |
| `ink-progress-bar` | Progress bars |
| `ink-table` | Data tables |
| `ink-link` | Terminal hyperlinks |
| `ink-gradient` | Gradient text |
| `ink-big-text` | Large ASCII text |
For full list, see [references/useful-components.md](references/useful-components.md).