Skip to content

PyModel/pythinker-code / .agents/skills/opentui

opentui

Verified

Build terminal UIs with OpenTUI. Covers core, components, audio, keymaps, React, Solid, plugins, testing, standalone executables, QR encoding, SSH, and Three.js WebGPU.

FileKindSize
SKILL.mdskill md5.4 KB
docs/bindings/react.mdxmarkdown11.0 KB
docs/bindings/solid.mdxmarkdown15.0 KB
docs/components/ascii-font.mdxmarkdown4.3 KB
docs/components/box.mdxmarkdown5.5 KB
docs/components/code.mdxmarkdown10.2 KB
docs/components/diff.mdxmarkdown4.2 KB
docs/components/frame-buffer.mdxmarkdown6.7 KB
docs/components/input.mdxmarkdown5.6 KB
docs/components/line-number.mdxmarkdown4.0 KB
docs/components/markdown.mdxmarkdown10.6 KB
docs/components/qr-code.mdxmarkdown4.3 KB
docs/components/scrollbar.mdxmarkdown2.3 KB
docs/components/scrollbox.mdxmarkdown7.5 KB
docs/components/select.mdxmarkdown6.2 KB
docs/components/slider.mdxmarkdown2.2 KB
docs/components/tab-select.mdxmarkdown6.0 KB
docs/components/text-table.mdxmarkdown9.0 KB
docs/components/text.mdxmarkdown4.5 KB
docs/components/textarea.mdxmarkdown7.7 KB
docs/components/time-to-first-draw.mdxmarkdown4.7 KB
docs/core-concepts/audio.mdxmarkdown32.2 KB
docs/core-concepts/colors.mdxmarkdown7.8 KB
docs/core-concepts/console.mdxmarkdown3.2 KB
docs/core-concepts/constructs.mdxmarkdown5.8 KB
docs/core-concepts/keyboard.mdxmarkdown10.4 KB
docs/core-concepts/layout.mdxmarkdown4.0 KB
docs/core-concepts/lifecycle.mdxmarkdown4.4 KB
docs/core-concepts/notifications.mdxmarkdown2.3 KB
docs/core-concepts/renderables-vs-constructs.mdxmarkdown4.5 KB
docs/core-concepts/renderables.mdxmarkdown9.9 KB
docs/core-concepts/renderer.mdxmarkdown30.9 KB
docs/core-concepts/testing.mdxmarkdown14.6 KB
docs/getting-started.mdxmarkdown3.2 KB
docs/keymap/addons.mdxmarkdown15.6 KB
docs/keymap/core.mdxmarkdown38.9 KB
docs/keymap/custom-addons.mdxmarkdown26.7 KB
docs/keymap/hosts.mdxmarkdown15.7 KB
docs/keymap/overview.mdxmarkdown18.1 KB
docs/keymap/react.mdxmarkdown4.9 KB
docs/keymap/solid.mdxmarkdown5.1 KB
docs/plugins/core.mdxmarkdown12.6 KB
docs/plugins/react.mdxmarkdown6.5 KB
docs/plugins/slots.mdxmarkdown12.7 KB
docs/plugins/solid.mdxmarkdown7.0 KB
docs/reference/color-matrix.mdxmarkdown3.8 KB
docs/reference/env-vars.mdxmarkdown6.5 KB
docs/reference/native-span-feed.mdxmarkdown6.0 KB
docs/reference/package-entrypoints.mdxmarkdown9.6 KB
docs/reference/qr-encoder.mdxmarkdown12.3 KB
docs/reference/ssh.mdxmarkdown14.8 KB
docs/reference/standalone-executables.mdxmarkdown7.1 KB
docs/reference/three.mdxmarkdown14.8 KB
docs/reference/tree-sitter.mdxmarkdown4.6 KB

docs/core-concepts/renderables.mdx

View on GitHub
---
title: Renderables
description: The building blocks of your terminal UI
order: 2
---

# Renderables

Renderables are the building blocks of your UI. You can position, style, and nest them within each other. Each renderable represents a visual element and uses the Yoga layout engine for flexible positioning and sizing.

## Creating Renderables

Create a renderable by instantiating a class with a render context (the renderer) and options:

```typescript
import { createCliRenderer, TextRenderable, BoxRenderable } from "@opentui/core"

const renderer = await createCliRenderer()

const greeting = new TextRenderable(renderer, {
  id: "greeting",
  content: "Hello, OpenTUI!",
  fg: "#00FF00",
})

renderer.root.add(greeting)
```

## Available Renderables

OpenTUI provides these built-in renderables:

| Class                                                              | Description                                   |
| ------------------------------------------------------------------ | --------------------------------------------- |
| `BoxRenderable`                                                    | Container with border, background, and layout |
| `TextRenderable`                                                   | Read-only styled text display                 |
| [`TextTableRenderable`](/docs/components/text-table)               | Styled, wrapping, selectable text table       |
| `InputRenderable`                                                  | Single-line text input                        |
| `TextareaRenderable`                                               | Multi-line editable text                      |
| `SelectRenderable`                                                 | Dropdown/list selection                       |
| `TabSelectRenderable`                                              | Horizontal tab selection                      |
| `ScrollBoxRenderable`                                              | Scrollable container                          |
| `ScrollBarRenderable`                                              | Standalone scroll bar control                 |
| `CodeRenderable`                                                   | Syntax-highlighted code display               |
| `LineNumberRenderable`                                             | Line number gutter for code/text views        |
| `DiffRenderable`                                                   | Unified or split diff viewer                  |
| `ASCIIFontRenderable`                                              | ASCII art font display                        |
| `FrameBufferRenderable`                                            | Raw framebuffer for custom graphics           |
| `MarkdownRenderable`                                               | Markdown renderer                             |
| `SliderRenderable`                                                 | Numeric slider control                        |
| [`TimeToFirstDrawRenderable`](/docs/components/time-to-first-draw) | First-draw performance timestamp display      |

QR code support is available from the separate `@opentui/qrcode` package.

## The Renderable Tree

Renderables form a tree structure. Use `add()` and `remove()` to manage children:

```typescript
const container = new BoxRenderable(renderer, {
  id: "container",
  flexDirection: "column",
  padding: 1,
})

const title = new TextRenderable(renderer, { id: "title", content: "My App" })
const body = new TextRenderable(renderer, { id: "body", content: "Content here" })

container.add(title)
container.add(body)

renderer.root.add(container)

// Later, remove a child by reference
container.remove(body)
```

## Finding Renderables

Navigate the tree to find specific renderables:

```typescript
// Get a direct child by ID
const title = container.getRenderable("title")

// Remove by ID lookup when needed
const body = container.getRenderable("body")
if (body) container.remove(body)

// Recursively search all descendants
const deepChild = container.findDescendantById("nested-input")

// Get all children
const children = container.getChildren()
```

## Layout Properties

All renderables support Yoga flexbox properties:

```typescript
const panel = new BoxRenderable(renderer, {
  id: "panel",

  // Sizing
  width: 40,
  height: "50%",
  minWidth: 20,
  maxHeight: 30,

  // Flex behavior
  flexGrow: 1,
  flexShrink: 0,
  flexDirection: "column",
  justifyContent: "center",
  alignItems: "flex-start",

  // Positioning
  position: "absolute",
  left: 10,
  top: 5,

  // Spacing
  padding: 2,
  paddingTop: 1,
  margin: 1,
})
```

See the [Layout](/docs/core-concepts/layout) page for complete details.

## Focus Management

Interactive renderables can receive keyboard focus:

```typescript
const input = new InputRenderable(renderer, {
  id: "username",
  placeholder: "Enter username...",
})

renderer.root.add(input)

// Give focus to the input
input.focus()

// Remove focus
input.blur()

// Check focus state
console.log(input.focused) // true
```

By default, left-clicking a renderable will auto-focus the closest focusable ancestor. Disable this globally with
`createCliRenderer({ autoFocus: false })`, or stop it per interaction by calling `event.preventDefault()` in
`onMouseDown`.

Listen for focus changes:

```typescript
import { RenderableEvents } from "@opentui/core"

input.on(RenderableEvents.FOCUSED, () => {
  console.log("Input focused")
})

input.on(RenderableEvents.BLURRED, () => {
  console.log("Input blurred")
})
```

### Focused descendants

A renderable can also react to focus living inside one of its descendants through the `hasFocusedDescendant` flag. When any child has focus, every ancestor's `hasFocusedDescendant` flips to `true` and OpenTUI marks them dirty so they repaint. `BoxRenderable` uses this to paint the `focusedBorderColor` whenever the box itself is focusable and any descendant currently owns focus:

```typescript
const panel = new BoxRenderable(renderer, {
  id: "panel",
  focusable: true,
  borderColor: "#444",
  focusedBorderColor: "#00AAFF",
  flexDirection: "column",
})

const input = new InputRenderable(renderer, { id: "panel-input" })
panel.add(input)

input.focus() // panel.hasFocusedDescendant === true → border recolors
```

Custom renderables can read `this._hasFocusedDescendant` (protected) or `renderable.hasFocusedDescendant` (public) to add similar effects.

## Event Handling

### Mouse Events

Handle mouse interactions via options:

```typescript
const button = new BoxRenderable(renderer, {
  id: "button",
  border: true,
  onMouseDown: (event) => {
    console.log("Clicked at", event.x, event.y)
  },
  onMouseOver: (event) => {
    button.borderColor = "#FFFF00"
  },
  onMouseOut: (event) => {
    button.borderColor = "#FFFFFF"
  },
})
```

Available mouse events:

- `onMouseDown`, `onMouseUp`
- `onMouseMove`, `onMouseDrag`, `onMouseDragEnd`, `onMouseDrop`
- `onMouseOver`, `onMouseOut`
- `onMouseScroll`
- `onMouse` (catch-all)

Mouse events bubble up through the tree. Stop propagation with `event.stopPropagation()`.

### Keyboard Events

For focusable renderables:

```typescript
const textDecoder = new TextDecoder()

const input = new InputRenderable(renderer, {
  id: "input",
  onKeyDown: (key) => {
    if (key.name === "escape") {
      input.blur()
    }
  },
  onPaste: (event) => {
    console.log("Pasted:", textDecoder.decode(event.bytes))
  },
})
```

## Visibility

Control visibility with the `visible` property:

```typescript
// Hide (also removes from layout)
panel.visible = false

// Show
panel.visible = true
```

When `visible` is `false`, Yoga excludes the renderable from layout calculation (equivalent to CSS `display: none`).

## Opacity

Set opacity for semi-transparent rendering:

```typescript
panel.opacity = 0.5 // 50% transparent
```

Opacity affects the renderable and all its children.

## Z-Index

Control layering order for overlapping elements:

```typescript
const overlay = new BoxRenderable(renderer, {
  id: "overlay",
  position: "absolute",
  zIndex: 100, // Higher values render on top
})
```

## Live Rendering

For animations, extend the Renderable class and override `onUpdate`:

```typescript
class AnimatedBox extends BoxRenderable {
  onUpdate(deltaTime) {
    // Update animation state
    this.translateX += 1
  }
}

const box = new AnimatedBox(renderer, {
  id: "anim-box",
  live: true, // Enable continuous rendering
})
```

## Translation

Offset a renderable from its layout position (useful for scrolling/animation):

```typescript
// Offset by pixels
renderable.translateX = 10
renderable.translateY = -5
```

This moves the renderable visually without affecting layout.

## Buffered Rendering

Enable offscreen rendering for complex content and use hooks to draw to the buffer:

```typescript
import { BoxRenderable, RGBA } from "@opentui/core"

const complex = new BoxRenderable(renderer, {
  id: "complex",
  buffered: true, // Render to offscreen buffer first
  renderAfter: (buffer) => {
    // Draw directly to the buffer (or offscreen buffer if buffered=true)
    buffer.fillRect(0, 0, 10, 5, RGBA.fromHex("#FF0000"))
  },
})
```

`renderBefore` and `renderAfter` are draw-only hooks for custom rendering and decorations. They run after layout and viewport culling, so do not mutate layout props, children, visibility, or reactive state from them.

## Lifecycle Methods

Override these methods in custom renderables:

```typescript
class CustomRenderable extends Renderable {
  // Called each frame before rendering
  onUpdate(deltaTime: number) {
    // Update state, animations, etc.
  }

  // Called when dimensions change
  onResize(width: number, height: number) {
    // Respond to size changes
  }

  // Called when removed from parent
  onRemove() {
    // Cleanup
  }

  // Override for custom rendering
  renderSelf(buffer: OptimizedBuffer, deltaTime: number) {
    // Draw to buffer
  }
}
```

## Destroying Renderables

Clean up a renderable and remove it from the tree:

```typescript
// Remove from parent and free resources
renderable.destroy()

// Destroy self and all children
container.destroyRecursively()
```
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall