Package Exports
- tuiuiu.js
- tuiuiu.js/app
- tuiuiu.js/atoms
- tuiuiu.js/core
- tuiuiu.js/design-system
- tuiuiu.js/hooks
- tuiuiu.js/molecules
- tuiuiu.js/organisms
- tuiuiu.js/package.json
- tuiuiu.js/primitives
- tuiuiu.js/storybook
- tuiuiu.js/templates
- tuiuiu.js/utils
Readme
๐ฆ Tuiuiu
Terminal UI Framework for the Modern Era
Build beautiful, reactive terminal apps with a Modern Component API.
Zero dependencies โข Signals-based โข Flexbox layout โข Full mouse support โข MCP Ready
50+ components. Pure Node.js. No C++ bindings. AI-powered development.
๐ Documentation ยท ๐ Quick Start ยท ๐จ Storybook ยท ๐ค MCP Server
Quick Start
npm install tuiuiu.jsimport { render, Box, Text, useState, useInput, useApp } from 'tuiuiu.js';
function Counter() {
const [count, setCount] = useState(0);
const { exit } = useApp();
useInput((char, key) => {
if (key.upArrow) setCount(c => c + 1);
if (key.downArrow) setCount(c => c - 1);
if (key.escape) exit();
});
return Box({ flexDirection: 'column', padding: 1, borderStyle: 'round' },
Text({ color: 'cyan', bold: true }, '๐ฆ Tuiuiu Counter'),
Text({ color: 'yellow', marginTop: 1 }, `Count: ${count()}`),
Text({ color: 'gray', dim: true }, 'โ/โ: change โข Esc: exit')
);
}
const { waitUntilExit } = render(Counter);
await waitUntilExit();What's Inside
| Category | Features |
|---|---|
| Core | Signal-based reactivity, Flexbox layout engine, Focus management, Event system |
| Primitives | Box, Text, Spacer, Newline, Fragment, Divider, Canvas |
| Atoms | Button, TextInput, Switch, Slider, Spinner, ProgressBar, Timer, Tooltip |
| Molecules | Select, MultiSelect, RadioGroup, Autocomplete, Table, Tabs, Tree, Calendar, CodeBlock, Markdown |
| Organisms | Modal, CommandPalette, DataTable, FileManager, SplitPanel, ScrollArea, Grid, OverlayStack |
| Templates | AppShell, Page, Header, StatusBar, VStack, HStack, Center, FullScreen |
| Data Viz | BarChart, LineChart, Sparkline, Heatmap, Gauge, BigText, Digits |
| DevTools | Layout Inspector, Event Logger, Performance Metrics, Component Storybook |
Real-World Examples
Build terminal apps that feel native. These examples recreate familiar CLI tools entirely in Tuiuiu:
|
๐ htop Process Monitor
|
๐ mtr Network Diagnostics
|
๐ก ping Network Latency
|
# Try them yourself
pnpm tsx examples/app-htop.ts # Process monitor with live updates
pnpm tsx examples/app-mtr.ts # Network route tracer
pnpm tsx examples/app-ping.ts # Network latency monitorGallery
๐ Real-time Dashboard
|
๐ฌ Chat Application
|
๐จ Component Storybook
|
๐ Interactive Forms
|
๐ WhatsApp Clone
|
๐๏ธ Drawing Canvas
|
Highlights
โก Signal-based Reactivity
Fine-grained reactivity without Virtual DOM overhead. Only what changes gets updated.
import { createSignal, createEffect } from 'tuiuiu.js';
const [count, setCount] = createSignal(0);
const doubled = () => count() * 2;
createEffect(() => console.log(`Count: ${count()}, Doubled: ${doubled()}`));
setCount(5); // โ "Count: 5, Doubled: 10"๐ฆ Flexbox Layout
Build complex layouts with the CSS Flexbox model you already know.
Box({
flexDirection: 'row',
justifyContent: 'space-between',
alignItems: 'center',
gap: 2,
padding: 1
},
Text({ color: 'blue' }, 'Left'),
Box({ flexGrow: 1 }),
Text({ color: 'red' }, 'Right')
)๐จ 50+ Ready-to-Use Components
From simple buttons to complex data tables, everything is included.
import { Select, Modal, DataTable, CommandPalette } from 'tuiuiu.js';
// Dropdown select
Select({
items: [
{ label: 'Option A', value: 'a' },
{ label: 'Option B', value: 'b' },
],
onSelect: (item) => console.log(item)
});
// Command palette (โK style)
CommandPalette({
commands: [
{ id: 'new', label: 'New File', shortcut: 'Ctrl+N' },
{ id: 'open', label: 'Open File', shortcut: 'Ctrl+O' },
],
onSelect: (cmd) => handleCommand(cmd)
});๐ฑ๏ธ Full Mouse Support
Click, hover, scroll, drag โ all mouse events work out of the box.
Box({
borderStyle: 'round',
onClick: () => console.log('Clicked!'),
onMouseEnter: () => setHover(true),
onMouseLeave: () => setHover(false),
onScroll: (delta) => scrollBy(delta),
},
Text({}, hover() ? '๐ฅ Hovering!' : 'Hover me')
)๐ Data Visualization
Render charts and graphs directly in the terminal.
import { BarChart, Sparkline, Gauge } from 'tuiuiu.js';
BarChart({
data: [
{ label: 'Mon', value: 10 },
{ label: 'Tue', value: 25 },
{ label: 'Wed', value: 15 },
],
color: 'cyan',
showValues: true
});
Sparkline({ data: [1, 5, 2, 8, 3, 9], width: 20, style: 'braille' });
Gauge({ value: 75, max: 100, label: 'CPU', color: 'green' });๐๏ธ Atomic Design + Tree Shaking
Components organized in a clear hierarchy. Import only what you need โ unused code is automatically removed from your bundle.
// Import everything (convenient for development)
import { Box, Button, Modal } from 'tuiuiu.js';
// Import by layer (optimized bundles)
import { Box, Text } from 'tuiuiu.js/primitives';
import { Button, Spinner } from 'tuiuiu.js/atoms';
import { Select, Table } from 'tuiuiu.js/molecules';
import { Modal, DataTable } from 'tuiuiu.js/organisms';
import { AppShell, Page } from 'tuiuiu.js/templates';
// Core systems
import { createSignal, createEffect } from 'tuiuiu.js/core';
import { useState, useInput, useMouse } from 'tuiuiu.js/hooks';
import { render, renderOnce } from 'tuiuiu.js/app';
// Utilities & extras
import { measureText, getVisibleWidth } from 'tuiuiu.js/utils';
import { BarChart, Gauge } from 'tuiuiu.js/design-system';All subpath imports
| Import | Contents |
|---|---|
tuiuiu.js |
Everything (main entry) |
tuiuiu.js/primitives |
Box, Text, Spacer, Fragment, Divider, Canvas |
tuiuiu.js/atoms |
Button, TextInput, Switch, Slider, Spinner, ProgressBar, Timer |
tuiuiu.js/molecules |
Select, MultiSelect, Table, Tabs, Tree, Calendar, CodeBlock |
tuiuiu.js/organisms |
Modal, CommandPalette, DataTable, FileManager, SplitPanel |
tuiuiu.js/templates |
AppShell, Page, VStack, HStack, StatusBar |
tuiuiu.js/core |
createSignal, createEffect, batch, calculateLayout |
tuiuiu.js/hooks |
useState, useEffect, useInput, useMouse, useFocus |
tuiuiu.js/app |
render, renderOnce, useApp |
tuiuiu.js/utils |
Text measurement, ANSI utilities |
tuiuiu.js/design-system |
Full design system (charts, forms, navigation) |
tuiuiu.js/storybook |
Component explorer utilities |
๐ Centralized Store
Built-in state management for complex applications.
import { createStore } from 'tuiuiu.js';
const reducer = (state = { count: 0 }, action) => {
switch (action.type) {
case 'INCREMENT': return { count: state.count + 1 };
case 'DECREMENT': return { count: state.count - 1 };
default: return state;
}
};
const store = createStore(reducer, { count: 0 });
store.subscribe(() => console.log(store.state()));
store.dispatch({ type: 'INCREMENT' });MCP Server
Build terminal UIs with AI. Tuiuiu includes a native Model Context Protocol server that lets Claude and other AI assistants help you build terminal applications.
# Start the MCP server
npx tuiuiu.js@latest mcpAdd to your .mcp.json for Claude Code integration:
{
"mcpServers": {
"tuiuiu": {
"command": "npx",
"args": ["tuiuiu", "mcp"]
}
}
}Now Claude has full access to Tuiuiu's 50+ components, hooks, themes, and examples. Ask it to build dashboards, forms, file browsers, or any terminal UI โ it knows the API.
Available tools: tuiuiu_list_components, tuiuiu_get_component, tuiuiu_get_hook, tuiuiu_search, tuiuiu_list_themes, tuiuiu_create_theme, tuiuiu_getting_started, tuiuiu_quickstart, tuiuiu_version, tuiuiu_api_patterns
Storybook
Tuiuiu includes a built-in component storybook for exploring all components:
# Run the storybook
npx tuiuiu storybookNavigate through categories, see live previews, and copy code examples.
Examples
# Clone and explore
git clone https://github.com/forattini-dev/tuiuiu.js
cd tuiuiu.js
pnpm install
# Real-world apps (featured)
pnpm tsx examples/app-htop.ts # Process monitor (htop clone)
pnpm tsx examples/app-mtr.ts # Network tracer (mtr clone)
pnpm tsx examples/app-ping.ts # Latency monitor (ping clone)
pnpm tsx examples/app-dashboard.ts # Real-time dashboard
pnpm tsx examples/app-chat.ts # Chat applicationDocumentation
| Topic | Link |
|---|---|
| Quick Start | โ Getting Started |
| Components | โ Component Reference |
| Hooks | โ Hooks API |
| Signals | โ Reactive State |
| Layout | โ Flexbox Guide |
| Theming | โ Theme System |
| Storybook | โ Component Explorer |
| MCP Server | โ AI Integration |
Numbers
| Metric | Value |
|---|---|
| Components | 50+ |
| Dependencies | 0 |
| Subpath Imports | 12 |
| Hooks | 15 |
| MCP Tools | 10 |
| Examples | 20+ |
| Border Styles | 10 |
| Named Colors | 18 |
| Tests | 5300+ |
| Tree Shakeable | โ |
| MCP Ready | โ |
Why "Tuiuiu"?
The Tuiuiu (Jabiru mycteria) is a majestic Brazilian bird โ the tallest flying bird in South America. Just like this bird stands out in its environment, Tuiuiu stands out in the terminal UI landscape: elegant, powerful, and distinctly Brazilian.
License
MIT ยฉ Forattini