# ratatui-tui

Walks your agent through building terminal UIs with ratatui: project templates, widgets, layout, async events. Useful when the app lives in a terminal.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 722 installs · ★ 17
- Author: blacktop
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/blacktop/dotfiles/tree/HEAD/ai/skills/ratatui-tui/SKILL.md
- Updated: 2026-10-18
- HTML: https://affpapa.org/en/nevibecode/skills/ratatui-tui

## What it does

This skill covers ratatui 0.30.x and the way apps are put together in that line. It ships project templates at four levels: hello-world for a first look, simple-app for single-screen tools, async-app when you need background tasks or network calls, and component-app for multiple views with config and logging. You either copy a template into your project or generate one with `cargo generate ratatui/templates`.

The pattern it pushes is Elm Architecture: model, message, update, view. You get StatefulWidget examples for lists and tables, layout split with `Layout::vertical` and `Layout::horizontal`, and the built-in state types such as `ListState` and `TableState`. Async input runs through crossterm's `EventStream` combined with `tokio::select!`. Image support goes through `ratatui-image` 11.x, loading animation through `tui-shimmer`.

Upgrading from 0.29 is where things bite. `block::Title` is gone, `layout::Alignment` became `HorizontalAlignment`, and `Flex::SpaceAround` now follows flexbox semantics. Turning off ratatui's `default-features` also drops `layout-cache`, and layout performance falls off a cliff unless you re-enable it by hand. Worth checking your `Cargo.toml` before a release. Building needs Rust 1.88 as MSRV and edition 2024.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add blacktop/dotfiles --skill ratatui-tui -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/ratatui-tui/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/ratatui-tui/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add blacktop/dotfiles --skill ratatui-tui -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/ratatui-tui/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add blacktop/dotfiles --skill ratatui-tui -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/ratatui-tui/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install blacktop/dotfiles ratatui-tui
```

2. **Manually: put the files in place**
- File: `.github/skills/ratatui-tui/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add blacktop/dotfiles --skill ratatui-tui -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/blacktop/dotfiles --path ai/skills/ratatui-tui
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/ratatui-tui/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add blacktop/dotfiles --skill ratatui-tui -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/blacktop/dotfiles/tree/HEAD/ai/skills/ratatui-tui/SKILL.md

## When to use it
- scaffold a new ratatui TUI from a template
- add a scrollable list or table with selection state
- split the screen into regions with Layout
- handle keyboard and background events in one loop
- fix layout after moving from 0.29 to 0.30

## Example prompts
- Create a new ratatui TUI from the simple-app template
- Add a scrollable table using TableState
- Rewrite the event loop with EventStream and tokio::select!

## Similar
- [tui-design](https://affpapa.org/en/nevibecode/skills/tui-design.md) — skill · 1300 installs
- [rattles-terminal-spinners](https://affpapa.org/en/nevibecode/skills/rattles-terminal-spinners.md) — skill · 497 installs
- [tui-validate](https://affpapa.org/en/nevibecode/skills/tui-validate.md) — skill · ★ 3186
- [opentui](https://affpapa.org/en/nevibecode/skills/opentui.md) — skill · 64500 installs
- [ink](https://affpapa.org/en/nevibecode/skills/ink.md) — skill · 1300 installs
- [control-cli](https://affpapa.org/en/nevibecode/skills/control-cli.md) — skill · 2400 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md