API

render(tree, options?)

Returns: Instance

Mount a component and render the output.

tree

Type: ReactElement

options

Type: object

stdout

Type: stream.Writable
Default: process.stdout

Output stream where app will be rendered.

stdin

Type: stream.Readable
Default: process.stdin

Input stream where app will listen for input.

stderr

Type: stream.Writable
Default: process.stderr

Error stream.

exitOnCtrlC

Type: boolean
Default: true

Configure whether Ink should listen for Ctrl+C keyboard input and exit the app. This is needed in case process.stdin is in raw mode, because then Ctrl+C is ignored by default and the process is expected to handle it manually.

patchConsole

Type: boolean
Default: true

Patch console methods to ensure console output doesn't mix with Ink's output. When any of the console.* methods are called (like console.log()), Ink intercepts their output, clears the main output, renders output from the console method, and then rerenders the main output again. That way, both are visible and don't overlap each other.

This functionality is powered by patch-console, so if you need to disable Ink's interception of output but want to build something custom, you can use that.

onRender

Type: ({renderTime: number}) => void
Default: undefined

Runs the given callback after each render and re-render with a metrics object.

debug

Type: boolean
Default: false

If true, each update will be rendered as separate output, without replacing the previous one.

maxFps

Type: number
Default: 30

Maximum frames per second for render updates. This controls how frequently the UI can update to prevent excessive re-rendering. Higher values allow more frequent updates but may impact performance. Setting it to a lower value may be useful for components that update very frequently, to reduce CPU usage.

incrementalRendering

Type: boolean
Default: false

Enable incremental rendering mode which only updates changed lines instead of redrawing the entire output. This can reduce flickering and improve performance for frequently updating UIs.

Instance

This is the object that render() returns.

rerender(tree)

Replace the previous root node with a new one or update props of the current root node.

tree

Type: ReactElement

// Update props of the root node
const {rerender} = render(<Counter count={1} />);
rerender(<Counter count={2} />);

// Replace root node
const {rerender} = render(<OldCounter />);
rerender(<NewCounter />);

unmount()

Manually unmount the whole Ink app.

const {unmount} = render(<MyApp />);
unmount();

waitUntilExit()

Returns a promise that resolves when the app is unmounted.

const {unmount, waitUntilExit} = render(<MyApp />);

setTimeout(unmount, 1000);

await waitUntilExit(); // resolves after `unmount()` is called

clear()

Clear output.

const {clear} = render(<MyApp />);
clear();

measureElement(ref)

Measure the dimensions of a particular <Box> element. Returns an object with width and height properties. This function is useful when your component needs to know the amount of available space it has. You can use it when you need to change the layout based on the length of its content.

Note: measureElement() returns correct results only after the initial render, when the layout has been calculated. Until then, width and height equal zero. It's recommended to call measureElement() in a useEffect hook, which fires after the component has rendered.

ref

Type: MutableRef

A reference to a <Box> element captured with the ref property. See Refs for more information on how to capture references.

Example

import {render, measureElement, Box, Text} from 'ink';

const Example = () => {
	const ref = useRef();

	useEffect(() => {
		const {width, height} = measureElement(ref.current);
		// width = 100, height = 1
	}, []);

	return (
		<Box width={100}>
			<Box ref={ref}>
				<Text>This box will stretch to 100 width</Text>
			</Box>
		</Box>
	);
};

render(<Example />);