opentui
Build terminal UIs with OpenTUI/React. Use when creating screens, components, handling keyboard input, managing scroll, or navigating between views. Covers JSX intrinsics, useKeyboard, scrollbox patterns, and state preservation. Use when this capability is needed.
Datos de origen
- Repositorio
- tomevault-io/skills-registry
- Última actividad en el origen
- 28 de abril de 2026 a las 22:53
- Idioma detectado de SKILL.md
- inglés
- Estrellas
- 0
- Forks
- 0
Opciones de instalación
De forma predeterminada está seleccionado el prompt que primero revisa el origen. Puedes cambiar a un comando directo o descargar una copia local.
Revisa los archivos de origen
Lee SKILL.md y los archivos complementarios que muestra SkillsMP antes de decidir si quieres instalarlo.
Explorador de archivos
2 archivosMostrando SKILL.md
SKILL.md
Instrucciones de origen · Vista previa de solo lectura- name
- opentui
- description
- Build terminal UIs with OpenTUI/React. Use when creating screens, components, handling keyboard input, managing scroll, or navigating between views. Covers JSX intrinsics, useKeyboard, scrollbox patterns, and state preservation. Use when this capability is needed.
- metadata
- {"author":"ainergiz"}
# OpenTUI/React Quick Reference
OpenTUI is a React renderer for terminal UIs using Yoga layout (like React Native). **NOT React DOM or Ink.**
## Version Info
- **Current:** 0.1.69 (updated), **Latest:** 0.1.69
- **Context repo:** `.context/repos/opentui` (run `bun run sync-context` if missing)
## Core Imports
```typescript
import { useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react";
import type { ScrollBoxRenderable, KeyEvent } from "@opentui/core";
```
## JSX Elements (Lowercase!)
```tsx
// CORRECT - OpenTUI intrinsics
<box style={{ flexDirection: "column" }}>
<text fg="#ffffff">Hello</text>
<scrollbox ref={scrollRef} focused />
</box>
// WRONG - Not OpenTUI
<div>, <span>, <Box>, <Text>
```
| Element | Purpose | Key Props |
|---------|---------|-----------|
| `<box>` | Container/layout | `style`, `id`, `onMouse` |
| `<text>` | Text content (strings only!) | `fg`, `bg`, `selectable` |
| `<scrollbox>` | Scrollable container | `ref`, `focused` |
| `<a>` | Hyperlink (OSC8) | `href`, `fg` |
| `<input>` | Text input | `focused`, `onInput`, `onSubmit` |
| `<textarea>` | Multi-line input | `ref`, `focused`, `placeholder` |
## Critical Rules
### 1. Text Only Accepts Strings
```tsx
// WRONG - Cannot nest elements in <text>
<text>Hello <text fg="red">world</text></text>
// CORRECT - Use row box for inline styling
<box style={{ flexDirection: "row" }}>
<text>Hello </text>
<text fg="red">world</text>
</box>
```
### 2. Always Check `focused` in Keyboard Handlers
```tsx
useKeyboard((key) => {
if (!focused) return; // MUST check first!
if (key.name === "j") moveDown();
});
```
### 3. Save Scroll Position Synchronously
```tsx
// WRONG - useEffect runs after render, scroll already reset
useEffect(() => { if (!focused) savedScroll.current = scrollRef.current?.scrollTop; }, [focused]);
// CORRECT - Save before state change
const handleSelect = () => {
savedScroll.current = scrollRef.current?.scrollTop; // Save first!
onSelect(item);
};
```
## Hyperlinks (New in 0.1.64+)
```tsx
<text>
Visit <a href="https://example.com">example.com</a> for more
</text>
```
Renders clickable links in terminals supporting OSC8 (iTerm2, Kitty, etc.).
## Key Names
| Key | `key.name` | | Key | `key.name` |
|-----|------------|--|-----|------------|
| Enter | `"return"` | | Arrows | `"up"`, `"down"`, `"left"`, `"right"` |
| Escape | `"escape"` | | Letters | `"a"`, `"b"`, `"j"`, `"k"` |
| Tab | `"tab"` | | Shift+Letter | `"A"`, `"B"`, `"G"` |
## Scrollbox API
```typescript
const scrollbox = scrollRef.current;
scrollbox.scrollTop // Current position
scrollbox.scrollHeight // Total content height
scrollbox.viewport.height // Visible area
scrollbox.scrollTo(pos) // Absolute scroll
scrollbox.scrollBy(delta) // Relative scroll
scrollbox.getChildren() // Find elements by ID
```
## Common Layout Patterns
```tsx
// Full-height with fixed header/footer
<box style={{ flexDirection: "column", height: "100%" }}>
<box style={{ flexShrink: 0 }}>{/* Header */}</box>
<scrollbox style={{ flexGrow: 1 }}>{/* Content */}</scrollbox>
<box style={{ flexShrink: 0 }}>{/* Footer */}</box>
</box>
// Prevent unwanted spacing (Yoga quirk)
<box style={{ justifyContent: "flex-start", marginBottom: 0, paddingBottom: 0 }}>
```
## React DevTools (Optional)
```bash
bun add --dev react-devtools-core@7
npx react-devtools@7 # Start standalone devtools
DEV=true bun run start # Run app with devtools enabled
```
## Detailed References
- [COMPONENTS.md](COMPONENTS.md) - JSX elements, styling, text nesting
- [KEYBOARD.md](KEYBOARD.md) - Keyboard handling, key names, focus patterns
- [SCROLLBOX.md](SCROLLBOX.md) - Scrollbox API, scroll preservation, windowed lists
- [LAYOUT.md](LAYOUT.md) - Flex layout, Yoga engine, spacing issues
- [PATTERNS.md](PATTERNS.md) - Screen navigation, state preservation, library compatibility
## xfeed Reference Files
- `src/app.tsx` - Screen routing, navigation history
- `src/components/PostList.tsx` - Scrollbox with preservation
- `src/components/PostCard.tsx` - Component styling, mouse handling
- `src/modals/FolderPicker.tsx` - Windowed list pattern
- `src/hooks/useListNavigation.ts` - Vim-style navigation
---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/ainergiz) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->
Ver en GitHub