https://github.com/nberlette/tui
Lightweight cross-runtime framework for building reactive Terminal User Interfaces (TUI) in TypeScript.
https://github.com/nberlette/tui
ansi bun cli deno framework nodejs reactive reactivity terminal terminal-app terminal-ui tui tui-library typescript
Last synced: 8 days ago
JSON representation
Lightweight cross-runtime framework for building reactive Terminal User Interfaces (TUI) in TypeScript.
- Host: GitHub
- URL: https://github.com/nberlette/tui
- Owner: nberlette
- License: mit
- Created: 2025-06-05T18:28:41.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-12T00:43:40.000Z (3 months ago)
- Last Synced: 2026-03-12T06:25:51.521Z (3 months ago)
- Topics: ansi, bun, cli, deno, framework, nodejs, reactive, reactivity, terminal, terminal-app, terminal-ui, tui, tui-library, typescript
- Language: TypeScript
- Homepage: https://jsr.io/@nick/tui/doc
- Size: 1.07 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# ⌨️ Tui
[](https://github.com/Im-Beast/deno_tui/actions/workflows/deno.yml)
[](https://doc.deno.land/https://deno.land/x/tui/mod.ts)
Simple [Deno](https://github.com/denoland/deno/) module that allows easy
creation of
[Terminal User Interfaces](https://en.wikipedia.org/wiki/Text-based_user_interface).
### 🔩 Features
- 🔰 Ease of use
- 👁️🗨️ Reactivity
- 🖇️ No dependencies
- 📄 Decent documentation
- [📦 Multiple ready-to-use components](./src/components/)
- 🎨 Styling framework agnostic
- This means you can use whatever terminal styling module you want
- [🖍️ Crayon](https://github.com/crayon-js/crayon) is recommended _but not
imposed_ as it greatly integrates with Tui
- 🪶 Relatively lightweight
## 🖥️ OS Support
| Operating system | Linux | macOS | Windows¹ | WSL |
| -------------------- | ----- | ----- | -------- | ---- |
| Base | ✔️ | ✔️ | ✔️ | ✔️ |
| Keyboard support | ✔️ | ✔️ | ✔️ | ✔️ |
| Mouse support | ✔️ | ✔️ | ✔️ | ✔️ |
| Required permissions | none | none | none | none |
¹ - If unicode characters are displayed incorrectly type `chcp 65001` into the
console to change active console code page to use UTF-8 encoding.
## 🎓 Get started
#### Replace {version} with relevant module versions
1. Create Tui instance
```ts
import { crayon } from "https://deno.land/x/crayon@$MODULE_VERSION/mod.ts";
import { Canvas, Tui } from "https://deno.land/x/tui@$MODULE_VERSION/mod.ts";
const tui = new Tui({
style: crayon.bgBlack, // Make background black
refreshRate: 1000 / 60, // Run in 60FPS
});
tui.dispatch(); // Close Tui on CTRL+C
```
2. Enable interaction using keyboard and mouse
```ts
import { handleInput, handleKeyboardControls, handleMouseControls } from "https://deno.land/x/tui@$MODULE_VERSION/mod.ts";
...
handleInput(tui);
handleMouseControls(tui);
handleKeyboardControls(tui);
```
3. Add some components
```ts
import { Button } from "https://deno.land/x/tui@$MODULE_VERSION/src/components/mod.ts";
import { Signal, Computed } from "https://deno.land/x/tui@$MODULE_VERSION/mod.ts";
...
// Create signal to make number automatically reactive
const number = new Signal(0);
const button = new Button({
parent: tui,
zIndex: 0,
label: {
text: new Computed(() => number.value.toString()), // cast number to string
},
theme: {
base: crayon.bgRed,
focused: crayon.bgLightRed,
active: crayon.bgYellow,
},
rectangle: {
column: 1,
row: 1,
height: 5,
width: 10,
},
});
// If button is active (pressed) make number bigger by one
button.state.when("active", (state) => {
++number.value;
});
// Listen to mousePress event
button.on("mousePress", ({ drag, movementX, movementY }) => {
if (!drag) return;
// Use peek() to get signal's value when it happens outside of Signal/Computed/Effect
const rectangle = button.rectangle.peek();
// Move button by how much mouse has moved while dragging it
rectangle.column += movementX;
rectangle.row += movementY;
});
```
4. Run Tui
```ts
...
tui.run();
```
## 🤝 Contributing
**Tui** is open for any contributions.
If you feel like you can enhance this project - please open an issue
and/or pull request.
Code should be well document and easy to follow what's going on.
This project follows
[conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) spec.
If your pull request's code can be hard to understand, please add
comments to it.
## 📝 Licensing
This project is available under **MIT** License conditions.