0
# Application Rendering
1
2
Core functionality for mounting and rendering React component trees to the terminal with full lifecycle management and stream control.
3
4
## Capabilities
5
6
### Render Function
7
8
The main function to mount a React component and render it to the terminal.
9
10
```typescript { .api }
11
/**
12
* Mount a component and render the output to terminal
13
* @param node - React component tree to render
14
* @param options - Rendering configuration or output stream
15
* @returns Instance object for controlling the rendered app
16
*/
17
function render(
18
node: ReactNode,
19
options?: NodeJS.WriteStream | RenderOptions
20
): Instance;
21
```
22
23
**Usage Examples:**
24
25
```typescript
26
import React from "react";
27
import { render, Box, Text } from "ink";
28
29
// Basic rendering
30
const instance = render(<Text>Hello World</Text>);
31
32
// With options
33
const instance = render(
34
<Box>
35
<Text color="green">Success!</Text>
36
</Box>,
37
{
38
stdout: process.stdout,
39
stdin: process.stdin,
40
exitOnCtrlC: true,
41
debug: false
42
}
43
);
44
45
// Using custom stream
46
const instance = render(<Text>Output</Text>, process.stderr);
47
```
48
49
### Render Options
50
51
Configuration options for controlling render behavior and stream handling.
52
53
```typescript { .api }
54
interface RenderOptions {
55
/**
56
* Output stream where app will be rendered
57
* @default process.stdout
58
*/
59
stdout?: NodeJS.WriteStream;
60
61
/**
62
* Input stream where app will listen for input
63
* @default process.stdin
64
*/
65
stdin?: NodeJS.ReadStream;
66
67
/**
68
* Error stream for error output
69
* @default process.stderr
70
*/
71
stderr?: NodeJS.WriteStream;
72
73
/**
74
* Render each update as separate output without replacing previous
75
* @default false
76
*/
77
debug?: boolean;
78
79
/**
80
* Listen to Ctrl+C and exit app automatically
81
* @default true
82
*/
83
exitOnCtrlC?: boolean;
84
85
/**
86
* Patch console methods to avoid mixing with Ink output
87
* @default true
88
*/
89
patchConsole?: boolean;
90
}
91
```
92
93
### Instance Control
94
95
The instance object returned by render provides control over the running application.
96
97
```typescript { .api }
98
interface Instance {
99
/**
100
* Replace previous root node with new one or update props
101
* @param node - New React component tree to render
102
*/
103
rerender: (node: ReactNode) => void;
104
105
/**
106
* Manually unmount the whole Ink app
107
*/
108
unmount: () => void;
109
110
/**
111
* Returns promise that resolves when app is unmounted
112
*/
113
waitUntilExit: () => Promise<void>;
114
115
/**
116
* Clean up instance resources
117
*/
118
cleanup: () => void;
119
120
/**
121
* Clear terminal output
122
*/
123
clear: () => void;
124
}
125
```
126
127
**Usage Examples:**
128
129
```typescript
130
import React, { useState } from "react";
131
import { render, Box, Text } from "ink";
132
133
function App() {
134
const [message, setMessage] = useState("Initial");
135
return <Text>{message}</Text>;
136
}
137
138
const instance = render(<App />);
139
140
// Update the app
141
setTimeout(() => {
142
instance.rerender(<Text color="green">Updated!</Text>);
143
}, 1000);
144
145
// Wait for completion
146
instance.waitUntilExit().then(() => {
147
console.log("App has exited");
148
});
149
150
// Clean up
151
instance.cleanup();
152
```
153
154
### Element Measurement
155
156
Utility for measuring the dimensions of rendered Box elements.
157
158
```typescript { .api }
159
/**
160
* Measure the dimensions of a particular Box element
161
* @param node - DOM element reference to measure
162
* @returns Object with width and height in terminal units
163
*/
164
function measureElement(node: DOMElement): {
165
width: number;
166
height: number;
167
};
168
```
169
170
**Usage Examples:**
171
172
```typescript
173
import React, { useRef, useEffect } from "react";
174
import { render, Box, Text, measureElement } from "ink";
175
176
function MeasuredBox() {
177
const boxRef = useRef<DOMElement>(null);
178
179
useEffect(() => {
180
if (boxRef.current) {
181
const { width, height } = measureElement(boxRef.current);
182
console.log(`Box size: ${width}x${height}`);
183
}
184
}, []);
185
186
return (
187
<Box ref={boxRef} width={20} height={5}>
188
<Text>Measured content</Text>
189
</Box>
190
);
191
}
192
193
render(<MeasuredBox />);
194
```
195
196
## Error Handling
197
198
Ink handles rendering errors and provides debugging capabilities:
199
200
- **Debug Mode**: Set `debug: true` in options to see each render update
201
- **Console Patching**: Automatically prevents console output from interfering with Ink rendering
202
- **Stream Management**: Proper cleanup of stdin/stdout/stderr listeners
203
- **Error Boundaries**: Standard React error boundaries work with Ink components
204
205
## Performance Considerations
206
207
- **Efficient Updates**: Only re-renders components that have changed
208
- **Layout Caching**: Yoga layout calculations are cached when possible
209
- **Stream Buffering**: Output is buffered to reduce terminal flicker
210
- **Memory Management**: Proper cleanup prevents memory leaks in long-running applications