fullscreen-ink

Create responsive, full-screen Ink terminal apps.

Usage

``bash
npm i fullscreen-ink
`

`jsx
import { withFullScreen } from "fullscreen-ink";

withFullScreen().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.

$3

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

`jsx
withFullScreen(, { exitOnCtrlC: false }).start();
`

$3

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:

`jsx
const ink = withFullScreen();
// ...
ink.instance.rerender();
`

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:

`jsx
const ink = withFullScreen();
await ink.start();
ink.instance.rerender();
`

$3

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

`jsx
const ink = withFullScreen();
// ...
await ink.waitUntilExit();
// do something after the app has closed
`

$3

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:

`js
import { useApp } from "ink";

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

$3

The hook used under the hood to obtain the screen size is useScreenSize, which returns an object with height and width properties that reflect the current size of the terminal (rows and columns in stdout). If you have an advanced use case, it is also available for direct use:

`js
import { useScreenSize } from "fullscreen-ink";

function MyComponent() {
const { height, width } = useScreenSize();
// use height and width as needed
}
`

How it works

Full screen is achieved through the combination of two things:

$3

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.

$3

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 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.