fullscreen-ink

Create responsive, full-screen Ink terminal apps.

Usage

npm i fullscreen-ink

import { withFullScreen } from "fullscreen-ink";

withFullScreen(<App />).start();

The app will be full-screen and will resize responsively as the terminal window changes size. After the app is closed, the previous content of the terminal will be restored.

Ink render options

You can pass any options that Ink's render function accepts to withFullScreen:

withFullScreen(<App />, { exitOnCtrlC: false }).start();

The Ink instance

If you need the Ink "instance" (normally returned from Ink's render function), you can access it through the instance property of the object returned from withFullScreen:

const ink = withFullScreen(<App />);
// ...
ink.instance.rerender(<SomethingElse />);

If you access it, keep in mind that due to how fullscreen-ink works, there might be a race condition unless you wait for the start method to resolve. For example:

const ink = withFullScreen(<App />);
await ink.start();
ink.instance.rerender(<SomethingElse />);

Waiting for the app to exit

Instead of calling waitUntilExit on the Ink instance, you must use the waitUntilExit property of the object:

const ink = withFullScreen(<App />);
// ...
await ink.waitUntilExit();
// do something after the app has closed

Exiting the app

If you use a method like process.exit to close the app, the terminal will likely be left in a weird state. Instead, you should use the exit method of Ink's useApp:

import { useApp } from "ink";

// somewhere in a component
const app = useApp();
app.exit();

How it works

Full screen is achieved through the combination of two things:

Alternate screen buffer

When the app starts, the terminal is switched to the alternate screen buffer. This means that the app will be the only thing visible in the terminal. When the app is closed, the previous content of the terminal will be restored.

This is similar to what happens when you run popular terminal apps like vim or less in the terminal.

FullScreenBox component

The FullScreenBox component is a simple Ink component that fills the entire terminal window. This is achieved by accessing the terminal's size through Ink's useStdout hook and rendering a box with the same dimensions. The size is updated on resize events, so the box will always fill the terminal window throughout its lifetime.

This component is automatically added to the root of the app when you use withFullScreen. If you need a custom layout (e.g. you want to add a border around the whole app), you can simply create an Ink <Box /> with flex-grow at the root of your app and it will fill the entire terminal window.

You can also use the component directly without withFullScreen, but you will have to handle the alternate screen buffer (if you want it) yourself. The component has the same API as Ink's Box component, except that it defaults to the width and height values that match the terminal window.