Shared from "Claude-Code" on Inkdown
How Claude Code renders its terminal UI using a custom React renderer.
Ink is a custom React renderer that targets the terminal instead of the DOM. It lets you write terminal UIs using React components and JSX.
// This renders in the terminal, not in a browser
<Box flexDirection="column" padding={1}>
<Text bold>Hello, Terminal!</Text>
<Text color="gray">This is Ink.</Text>
</Box>┌─────────────────────────────────────────────────────────┐
│ React Components │
│ <Box>, <Text>, <Button>, etc. │
└────────────────────────┬────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────┐
│ React Reconciler │
│ (react-reconciler host config) │
│ │
│ createInstance, appendChild, commitUpdate, etc. │
│ Maps React elements to Ink DOM nodes │
└────────────────────────┬────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────┐
│ Ink DOM │
│ DOM nodes with Yoga layout nodes │
│ <ink-box>, <ink-text>, <ink-virtual-text> │
└────────────────────────┬────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────┐
│ Yoga Layout (WASM) │
│ Flexbox layout engine │
└────────────────────────┬────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────┐
│ Renderer │
│ Walks DOM tree → writes to Output buffer │
└────────────────────────┬────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────┐
│ Frame │
│ Double-buffered screen (frontFrame, backFrame) │
└────────────────────────┬────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────┐
│ Diff │
│ Compare backFrame vs frontFrame → patches │
└────────────────────────┬────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────┐
│ Terminal Output │
│ ANSI escape sequences → stdout │
└──────────────────────────────────────────────────────────┘ink.render(reactNode)
→ reconciler.updateContainerSync(node)
→ reconciler.flushSyncWork()The user's component tree is wrapped in context providers:
App — stdin, keyboard, mouse, suspend/resumeThemeProvider — theme contextTerminalSizeContext — terminal dimensionsTerminalFocusContext — focus stateAfter React commits, resetAfterCommit fires:
resetAfterCommit(rootNode) {
rootNode.onComputeLayout() // Yoga layout
rootNode.onRender() // Throttled paint cycle
}Yoga is a flexbox layout engine compiled to WASM. Every Ink DOM node has an associated Yoga node:
// When creating an element:
const yogaNode = Yoga.Node.create()
Yoga.Node.setStyle(yogaNode, Yoga.PROPERTY_FLEX_DIRECTION, Yoga.FLEX_DIRECTION_COLUMN)
Yoga.Node.setStyle(yogaNode, Yoga.PROPERTY_PADDING, 10)
// When computing layout:
Yoga.Node.calculateLayout(rootYogaNode, terminalWidth, undefined, Yoga.DIRECTION_LTR)The renderer walks the DOM tree and writes to an Output buffer:
function renderer() {
// Validate dimensions
if (!width || !height) return emptyFrame
// Allocate screen
const screen = backFrame.screen ?? Screen.create(width, height)
const output = new Output(width, height)
// Walk tree
renderNodeToOutput(rootNode, output, { prevScreen: frontFrame.screen })
// Build frame
return new Frame(screen, width, height, cursorPosition)
}Blit optimization: If a subtree hasn't changed, it's bulk-copied from the previous frame's screen buffer instead of re-rendering children:
// In renderNodeToOutput:
if (prevScreen && !nodeDirty) {
output.blit(prevScreen, x, y, width, height) // Fast memcpy
return
}
// Otherwise, render children recursivelyThe new frame is diffed against the previous frame:
diffEach(prevScreen, nextScreen, (x, y, oldCell, newCell) => {
// Record the change
})The diff algorithm:
The diff produces terminal escape sequences:
\x1b[H — Cursor home (alt-screen anchoring)
\x1b[2J — Clear screen
\x1b[31mHello — Red text
\x1b[0m — Reset
\x1b[10;20H — Move cursor to row 10, column 20Key behaviors:
The Screen is the pixel buffer — a packed Int32Array:
Each cell = 2 words (8 bytes):
Word 0: charId (index into CharPool)
Word 1: styleId[31:17] | hyperlinkId[16:2] | width[1:0]This packed layout halves memory accesses and enables future SIMD comparison.
Interns ANSI style arrays into integer IDs:
// Instead of storing ["\x1b[31m", "\x1b[1m"] per cell,
// store a single integer ID that maps to those styles
const styleId = StylePool.intern(["\x1b[31m", "\x1b[1m"])Features:
transition(fromId, toId)) for zero-allocation ANSI stringsInterns character strings with an ASCII fast-path:
// ASCII characters (code < 128): direct Int32Array lookup
// Non-ASCII: interned string with ID
const charId = CharPool.intern("A") // Fast path: returns 65<Box>The fundamental layout primitive — equivalent to <div style="display:flex">:
<Box flexDirection="column" padding={1} gap={1}>
<Text>Hello</Text>
<Text>World</Text>
</Box>Supports: flex direction, grow, shrink, wrap, margins, padding, gaps, overflow, event handlers (click, focus, hover, keydown).
<Text>Displays styled text:
<Text bold color="red" wrap="truncate-end">
Hello World
</Text>Supports: color, background, bold, dim, italic, underline, strikethrough, inverse, text wrapping modes.
<ScrollBox>A Box with overflow scroll and imperative scroll API:
const scrollRef = useRef<ScrollBoxHandle>(null)
<ScrollBox ref={scrollRef}>
{longContent}
</ScrollBox>Features: viewport culling (only renders visible children), sticky scroll (auto-follow), scrollTo/scrollBy/scrollToBottom.
| Component | Purpose |
|---|---|
<Button> | Clickable button with state management |
<Link> | Clickable link (OSC 8 hyperlinks) |
<AlternateScreen> | Fullscreen mode (alternate screen buffer) |
<NoSelect> | Non-selectable region (gutters, line numbers) |
| Component | Purpose |
|---|---|
<Spacer> | Flexible spacing |
<Newline> | Insert newline(s) |
<RawAnsi> | Render raw ANSI escape sequences |
<ErrorOverview> | Error boundary display |
<App>)The root component that wraps everything:
The <App> component parses keyboard input:
// Key events are dispatched through the reconciler
dispatcher.dispatchDiscrete(() => {
// All state updates from this input burst are batched
})Special handling:
Mouse events are tracked in <AlternateScreen> mode:
Rendering is throttled to ~60fps (16ms frame interval):
const onRender = throttle(() => {
const frame = renderer()
const patches = diff(frontFrame, frame)
writePatchesToTerminal(patches)
frontFrame = frame
}, FRAME_INTERVAL_MS)Shared resource pools avoid per-frame allocations:
StylePool — interned style IDsCharPool — interned character IDsHyperlinkPool — interned hyperlink IDs<ScrollBox> only renders children in the visible window, not the entire scrollable content.
process.stdout.on('resize', () => {
// Recalculate layout with new dimensions
// Re-render with new terminal size
})process.on('SIGTSTP', () => {
// Exit alt screen, restore terminal
})
process.on('SIGCONT', () => {
// Re-enter alt screen, re-render
})The <AlternateScreen> component:
ink.ts)// Render a component tree
render(node: ReactElement): { unmount(): void }
// Create a root for incremental rendering
createRoot(container: Element): { render(node: ReactElement): void }
// Components
export { Box, Text, Button, Link, ScrollBox, Spacer, Newline, ... }
// Hooks
export { useInput, useApp, useStdin, useInterval, useAnimationFrame, ... }
// Theme
export { ThemeProvider, useTheme, useThemeSetting, color }| File | Purpose |
|---|---|
src/ink.ts | Public API (render, createRoot, exports) |
src/ink/ink.tsx | Ink class — central orchestrator |
src/ink/reconciler.ts | React reconciler host config |
src/ink/renderer.ts | Tree walk → Output buffer |
src/ink/output.ts | Operation recorder (write, blit, clear, clip) |
src/ink/screen.ts | Pixel buffer (Int32Array), StylePool, CharPool |
src/ink/log-update.ts | Diff → terminal escape sequences |
src/ink/root.ts | Root component management |
src/ink/components/App.tsx | Root app component (input, suspend, mouse) |
src/ink/components/Box.tsx | Layout primitive |
src/ink/components/Text.tsx | Text display |
src/ink/components/ScrollBox.tsx | Scrollable container |
src/ink/components/Button.tsx | Interactive button |
src/ink/components/AlternateScreen.tsx | Fullscreen mode |