Guide · Open source

How to use Ink: build React-based command-line apps

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Ink is an open-source library that lets you build terminal programs using React components. This guide shows you how to install it with npm, render a component in the terminal, and understand the core pieces (components, hooks and testing) so you can build a command-line app that updates over time or responds to input.

Inkvadimdemedes/ink · ★ 40.2k · MIT Install options & downloads

Quick start

1Check prerequisites. Make sure Node.js and npm are installed on your machine.
2Create or open a project. Start a Node.js project in the folder where you want your CLI to live.
3Install Ink and React. Run npm install ink react in the project folder.
4Write a component. Create a React component that returns Text or Box elements describing your output.
5Render it. Call render() from ink with your root component, as shown in the README example.
6Add state or input. Use useState, useEffect and hooks such as useInput to make the output update or respond to keys.

What Ink is and who it is for

Ink provides the same component-based UI building experience that React offers in the browser, but for command-line apps. It uses Yoga to build Flexbox layouts in the terminal, so most CSS-like properties are available in Ink as well.

Ink suits JavaScript or TypeScript developers who already know React and want a CLI that updates over time or responds to input. If you only need plain text output from a simple script, Ink adds React as a dependency and may be more than you need.

Install Ink and React with npm

Ink is installed with a package manager. The prerequisites are Node.js and npm. Install Ink and React together in your project with the command below.

The README notes that it documents the upcoming version of Ink. For the latest stable release, check Ink on npm.

npm install ink react

Render your first component

Import render and Text from ink, define a component, and pass it to render. The example below is the README's counter, which increments every 100 milliseconds using useState and useEffect and clears its timer on unmount.

Save the code in a file and run it with Node.js. Any JSX needs to be compiled first, so use a setup that supports JSX in your project.

Import React hooks from react and render and Text from ink.
Use useState to hold changing values.
Use useEffect with setInterval, and return a cleanup function that calls clearInterval.
Pass your root component to render().

import React, {useState, useEffect} from 'react';
import {render, Text} from 'ink';

const Counter = () => {
	const [counter, setCounter] = useState(0);

	useEffect(() => {
		const timer = setInterval(() => {
			setCounter(previousCounter => previousCounter + 1);
		}, 100);

		return () => {
			clearInterval(timer);
		};
	}, []);

	return <Text color="green">{counter} tests passed</Text>;
};

render(<Counter />);

Learn the main components and hooks

Ink's documented components include Text, Box, Newline, Spacer, Static and Transform. Box is the layout container, and Text displays styled text. The README documents hooks such as useInput for keyboard input, useApp, useStdin, useStdout, useFocus and useAnimation.

Because Ink is a React renderer, all React features are supported. The README points to the React website for general React documentation and documents only Ink's own methods.

Text: display styled text, for example with a color prop.
Box: lay out child elements with Flexbox-style properties.
useInput: react to keyboard input.
useApp: access app-level controls.
useAnimation: drive animated output.

Test CLI output by rendering components

One reason teams use Ink is that you can build and test your CLI output using components. The README lists testing as a dedicated section, so check that section of the Ink documentation for the current approach.

Start faster with a template or the README's examples

The README's Getting Started section points to create-ink-app for a starting project. The README also lists real projects that use Ink, such as Claude Code, Gemini CLI, Wrangler and Shopify CLI, and says that Examples and Recipes sections exist for further reference.

What people use it for

A counter or progress display that updates while a task runs, like the README's example.
An interactive command-line tool that reacts to keyboard input through useInput.
A CLI whose output is built from reusable components that can also be rendered in tests.
Live status screens in developer tools, similar to projects listed in the README such as Kubelive and Autarky.

Frequently asked questions

How do I install Ink?

Run npm install ink react in your project. The README lists Node.js and npm as the prerequisites for this package-manager install.

Is Ink free to use?

Yes. The repository is licensed under the MIT licence, which is shown in the project's summary. Check the LICENSE file in the repository for the full terms.

Do I need to know React to use Ink?

Yes. Ink is a React renderer, so you write your CLI as React components. The README says that if you already know React, you already know Ink.

Can I use Ink with TypeScript?

The project is written in TypeScript. The README does not give a TypeScript setup guide, so check the repository and the create-ink-app project for examples.

What are alternatives to Ink?

Comparable projects include blessed, Ink-based create-ink-app templates, and Commander.js. Choose based on whether you want React components, a full terminal UI library, or a command parser.

Why does my Ink code not run?

Common causes are a missing install of ink or react, or JSX that has not been compiled. Run npm install ink react again and confirm your project can handle JSX before rendering.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Ink is a good fit for JavaScript or TypeScript developers who already know React and want interactive or live-updating command-line output. It is not a good choice for simple plain-text scripts, for non-developers, or for projects that cannot use Node.js tooling.

Install options & downloads