# Ink

> Comprehensive Ink skill for building CLI applications with React. Covers components (Text, Box, Static, Transform), hooks (useInput, useApp, useFocus), Flexbox layout, testing, and accessibility.

- Skill: `thanhdongnguyen/ink` (Agent Skill, multi-file: 24 files)
- Install (CLI): `npx skillmds@latest add thanhdongnguyen/ink`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thanhdongnguyen/ink/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: thanhdongnguyen (https://skillmd.com/u/thanhdongnguyen)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thanhdongnguyen/ink

---


# Ink Platform Skill

Consolidated skill for building CLI applications with Ink (React for CLIs). Use decision trees below to find the right components and patterns, then load detailed references.

## Critical Rules

**Follow these rules in all Ink code:**

1. **All text must be wrapped in `<Text>`.** Raw strings outside `<Text>` will throw an error.
2. **`<Text>` only allows text nodes and nested `<Text>`.** You cannot nest `<Box>` inside `<Text>`.
3. **`<Box>` is always `display: flex`.** Think of every `<Box>` as `<div style="display: flex">`.
4. **Use `useApp().exit()` to exit.** Never call `process.exit()` directly from within components.
5. **Install both `ink` and `react`.** They are peer dependencies: `npm install ink react`.
6. **`<Static>` only renders new items.** Changes to previously rendered items are ignored.

## How to Use This Skill

### Reference File Structure

Core references follow a 5-file pattern. Cross-cutting concepts are single-file guides.

`./references/core/` contains:

| File | Purpose | When to Read |
|------|---------|--------------|
| `REFERENCE.md` | Overview, when to use, quick start | **Always read first** |
| `api.md` | render(), renderToString(), Instance, measureElement | Writing code |
| `configuration.md` | Render options, environment vars | Configuring an app |
| `patterns.md` | Common patterns, best practices | Implementation guidance |
| `gotchas.md` | Pitfalls, limitations, debugging | Troubleshooting |

Component, hook, and concept references in `./references/<area>/` have `REFERENCE.md` as the entry point.

### Reading Order

1. Start with `core/REFERENCE.md` for project overview
2. Then read additional files relevant to your task:
   - Building UI -> `components/REFERENCE.md` + specific component files
   - Handling input -> `hooks/input.md`
   - Layout/positioning -> `layout/REFERENCE.md`
   - App lifecycle -> `hooks/app-lifecycle.md`
   - Focus management -> `hooks/focus.md`
   - Testing -> `testing/REFERENCE.md`
   - Accessibility -> `accessibility/REFERENCE.md`
   - Troubleshooting -> `core/gotchas.md`
   - **Best practices / rules** -> `rules/RULES.md` + specific rule files

### Example Paths

```
./references/core/REFERENCE.md             # Start here
./references/core/api.md                   # render(), renderToString()
./references/components/text.md            # <Text> component
./references/components/box.md             # <Box> component (layout, borders)
./references/hooks/input.md                # useInput hook
./references/layout/patterns.md            # Common layout recipes
./references/testing/REFERENCE.md          # ink-testing-library
./rules/RULES.md                           # Best practices entry point
./rules/performance.md                     # FPS, Static, memoization
./rules/components.md                      # Per-component rules
./rules/hooks.md                           # Per-hook rules
./rules/core.md                            # render(), errors, environment
```

## Quick Decision Trees

### "I need to display content"

```
Display content?
├─ Plain or styled text -> components/text.md
├─ Container with layout -> components/box.md
├─ Container with borders -> components/box.md (borderStyle)
├─ Container with background color -> components/box.md (backgroundColor)
├─ Line breaks within text -> components/utilities.md (Newline)
├─ Flexible spacer -> components/utilities.md (Spacer)
├─ Permanent log output (completed items) -> components/utilities.md (Static)
└─ Transform text output (uppercase, gradient) -> components/utilities.md (Transform)
```

### "I need user input"

```
User input?
├─ Keyboard shortcuts/arrow keys -> hooks/input.md (useInput)
├─ Raw stdin access -> hooks/stdio.md (useStdin)
├─ Tab/Shift+Tab focus cycling -> hooks/focus.md (useFocus)
├─ Programmatic focus control -> hooks/focus.md (useFocusManager)
└─ Cursor positioning (IME) -> hooks/focus.md (useCursor)
```

### "I need layout/positioning"

```
Layout?
├─ Horizontal row of elements -> layout/REFERENCE.md (flexDirection: row)
├─ Vertical stack of elements -> layout/REFERENCE.md (flexDirection: column)
├─ Centering content -> layout/patterns.md
├─ Spacing between elements -> layout/REFERENCE.md (gap, margin, padding)
├─ Fixed width/height -> components/box.md (width, height)
├─ Percentage sizing -> components/box.md (width: "50%")
├─ Min/max constraints -> components/box.md (minWidth, maxWidth, maxHeight)
├─ Push elements apart -> components/utilities.md (Spacer)
├─ Flex grow/shrink -> layout/REFERENCE.md (flexGrow, flexShrink)
├─ Wrapping content -> layout/REFERENCE.md (flexWrap)
├─ Overflow control -> components/box.md (overflow)
└─ Complex nested layouts -> layout/patterns.md
```

### "I need to manage app lifecycle"

```
App lifecycle?
├─ Mount and render -> core/api.md (render)
├─ Render to string (no terminal) -> core/api.md (renderToString)
├─ Exit the app programmatically -> hooks/app-lifecycle.md (useApp, exit)
├─ Wait for app to finish -> core/api.md (waitUntilExit)
├─ Re-render with new props -> core/api.md (rerender)
├─ Unmount the app -> core/api.md (unmount)
└─ Write to stdout/stderr outside Ink -> hooks/stdio.md
```

### "I need to test my CLI"

```
Testing?
├─ Render and check output -> testing/REFERENCE.md
├─ Simulate user input -> testing/REFERENCE.md (stdin.write)
├─ Snapshot testing -> testing/REFERENCE.md
└─ Check last rendered frame -> testing/REFERENCE.md (lastFrame)
```

### "I need accessibility"

```
Accessibility?
├─ Screen reader support -> accessibility/REFERENCE.md
├─ ARIA roles (checkbox, button, etc.) -> accessibility/REFERENCE.md
├─ ARIA state (checked, disabled, etc.) -> accessibility/REFERENCE.md
├─ Custom screen reader labels -> accessibility/REFERENCE.md (aria-label)
└─ Hide from screen readers -> accessibility/REFERENCE.md (aria-hidden)
```

### "I need to debug/troubleshoot"

```
Troubleshooting?
├─ Text rendering issues -> core/gotchas.md
├─ Layout problems -> core/gotchas.md + layout/REFERENCE.md
├─ Input not working -> core/gotchas.md + hooks/input.md
├─ Process not exiting -> core/gotchas.md
├─ CI rendering issues -> core/configuration.md (CI mode)
├─ Console output mixing -> core/configuration.md (patchConsole)
└─ Performance/flickering -> core/configuration.md + rules/performance.md
```

### "I want best practices / production-ready code"

```
Best practices?
├─ General rules (critical) -> rules/RULES.md
├─ Performance (FPS, Static, memoization) -> rules/performance.md
├─ Per-component patterns & anti-patterns -> rules/components.md
├─ Per-hook patterns & gotchas -> rules/hooks.md
└─ render() / errors / environment behavior -> rules/core.md
```

### Troubleshooting Index

- Text outside `<Text>` -> `core/gotchas.md`
- `<Box>` inside `<Text>` -> `core/gotchas.md`
- Process hanging/not exiting -> `core/gotchas.md`
- Console.log mixing with output -> `core/configuration.md`
- Layout misalignment -> `layout/REFERENCE.md`
- Input not received -> `hooks/input.md` + `rules/hooks.md`
- Focus not cycling -> `hooks/focus.md` + `rules/hooks.md`
- CI output issues -> `core/configuration.md` + `rules/core.md`
- Flickering/performance -> `core/configuration.md` + `rules/performance.md`
- Anti-patterns / pitfalls -> `rules/components.md`, `rules/hooks.md`, `rules/core.md`

## Product Index

### Core
| Area | Entry File | Description |
|------|------------|-------------|
| Core | `./references/core/REFERENCE.md` | Overview, quick start, project setup |
| API | `./references/core/api.md` | render, renderToString, Instance |
| Config | `./references/core/configuration.md` | Render options, environment variables |
| Patterns | `./references/core/patterns.md` | Common patterns and recipes |
| Gotchas | `./references/core/gotchas.md` | Pitfalls and debugging |

### Components
| Component | Entry File | Description |
|-----------|------------|-------------|
| Overview | `./references/components/REFERENCE.md` | All components at a glance |
| Text | `./references/components/text.md` | Text display and styling |
| Box | `./references/components/box.md` | Layout, borders, backgrounds |
| Utilities | `./references/components/utilities.md` | Newline, Spacer, Static, Transform |

### Hooks
| Hook | Entry File | Description |
|------|------------|-------------|
| Overview | `./references/hooks/REFERENCE.md` | All hooks at a glance |
| Input | `./references/hooks/input.md` | useInput for keyboard handling |
| App Lifecycle | `./references/hooks/app-lifecycle.md` | useApp for exit control |
| Stdio | `./references/hooks/stdio.md` | useStdin, useStdout, useStderr |
| Focus | `./references/hooks/focus.md` | useFocus, useFocusManager, useCursor |

### Cross-Cutting Concepts
| Concept | Entry File | Description |
|---------|------------|-------------|
| Layout | `./references/layout/REFERENCE.md` | Yoga/Flexbox layout system |
| Layout Patterns | `./references/layout/patterns.md` | Common layout recipes |
| Testing | `./references/testing/REFERENCE.md` | ink-testing-library |
| Accessibility | `./references/accessibility/REFERENCE.md` | Screen reader & ARIA support |

### Best Practices (Rules)
| Rule File | Entry File | Description |
|-----------|------------|-------------|
| Overview | `./rules/RULES.md` | Entry point + 10 critical rules |
| Performance | `./rules/performance.md` | FPS tuning, Static, memoization, incremental rendering |
| Components | `./rules/components.md` | Box, Text, Static, Transform, Newline, Spacer rules |
| Hooks | `./rules/hooks.md` | useInput, useApp, useFocus, useCursor, useStdin rules |
| Core | `./rules/core.md` | render(), renderToString(), errors, CI, Kitty protocol |

## Resources

**Repository**: https://github.com/vadimdemedes/ink
**npm**: https://www.npmjs.com/package/ink
**Testing Library**: https://github.com/vadimdemedes/ink-testing-library
**Create Ink App**: https://github.com/vadimdemedes/create-ink-app