https://github.com/daniguardiola/fullscreen-ink
Create fullscreen command line apps with Ink.
https://github.com/daniguardiola/fullscreen-ink
Last synced: about 1 year ago
JSON representation
Create fullscreen command line apps with Ink.
- Host: GitHub
- URL: https://github.com/daniguardiola/fullscreen-ink
- Owner: DaniGuardiola
- License: mit
- Created: 2023-11-16T19:49:49.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-06T14:29:35.000Z (over 2 years ago)
- Last Synced: 2025-03-23T21:45:47.644Z (about 1 year ago)
- Language: TypeScript
- Size: 58.6 KB
- Stars: 29
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# fullscreen-ink
Create responsive, full-screen Ink terminal apps.
## Usage
```bash
npm i fullscreen-ink
```
```js
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.
### Ink `render` options
You can pass any options that Ink's `render` function accepts to `withFullScreen`:
```js
withFullScreen(, { 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`:
```js
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:
```js
const ink = withFullScreen();
await ink.start();
ink.instance.rerender();
```
### Waiting for the app to exit
Instead of calling `waitUntilExit` on the Ink instance, you must use the `waitUntilExit` property of the object:
```js
const ink = withFullScreen();
// ...
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`:
```js
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 `` 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.