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/constructs.mdx

View on GitHub
---
title: Constructs
description: Declarative component composition with VNodes
order: 3
---

# Constructs

Constructs let you compose your UI in a declarative, React-like way. They are factory functions that create VNodes (virtual nodes). A VNode is a lightweight description of a component. When you add a VNode to the tree, it becomes an actual Renderable.

## Basic Usage

Constructs look like function calls that return component descriptions:

```typescript
import { createCliRenderer, Box, Text, Input } from "@opentui/core"

const renderer = await createCliRenderer()

renderer.root.add(
  Box(
    { width: 40, height: 10, borderStyle: "rounded", padding: 1 },
    Text({ content: "Welcome!" }),
    Input({ placeholder: "Enter your name..." }),
  ),
)
```

Pass children as additional arguments after the props object, not as a property.

## Available Constructs

Most core Renderable classes have matching construct functions:

```typescript
import {
  ASCIIFont,
  Box,
  Code,
  FrameBuffer,
  Input,
  ScrollBox,
  Select,
  SyntaxStyle,
  TabSelect,
  Text,
  RGBA,
} from "@opentui/core"

// These create VNodes, not actual Renderables
const syntaxStyle = SyntaxStyle.fromStyles({
  default: { fg: RGBA.fromHex("#FFFFFF") },
})
const box = Box({ border: true })
const text = Text({ content: "Hello" })
const input = Input({ placeholder: "Type here..." })
const code = Code({ content: "const x = 1", filetype: "typescript", syntaxStyle })
const scrollBox = ScrollBox({ width: 40, height: 10 })
const frameBuffer = FrameBuffer({ width: 20, height: 10 })
const ascii = ASCIIFont({ text: "OPEN", font: "tiny" })
```

## How Constructs Work

When you call a construct like `Box()`, it creates a VNode - a plain object describing what to create:

```typescript
// This creates a VNode, not an actual BoxRenderable
const myBox = Box({ width: 20, height: 10 })

// The VNode is instantiated when added to the tree
renderer.root.add(myBox) // Now it becomes a real BoxRenderable
```

This deferred creation lets you:

- Compose UI without a render context
- Queue method calls before the component exists
- Write cleaner, more declarative code

## Creating Custom Constructs

Create reusable components by writing functions that return VNodes:

```typescript
function LabeledInput(props: { label: string; placeholder: string }) {
  return Box(
    { flexDirection: "row", gap: 1 },
    Text({ content: props.label }),
    Input({ placeholder: props.placeholder, width: 20 }),
  )
}

renderer.root.add(
  Box(
    { flexDirection: "column", padding: 1 },
    LabeledInput({ label: "Name:", placeholder: "Enter name..." }),
    LabeledInput({ label: "Email:", placeholder: "Enter email..." }),
  ),
)
```

## Method Chaining on VNodes

VNodes support method calls. The system queues these calls and applies them after creating the component:

```typescript
const input = Input({ id: "my-input", placeholder: "Type here..." })

// The VNode queues this call
input.focus()

// When added, the system creates the input and calls focus()
renderer.root.add(input)
```

You can also set properties:

```typescript
const box = Box({ id: "my-box" })
box.backgroundColor = RGBA.fromHex("#333366")
renderer.root.add(box)
```

## The delegate() Function

Composite components often need outer method calls to reach a specific inner component. The `delegate()` function maps method and property names to descendant IDs:

```typescript
import { delegate, Box, Text, Input } from "@opentui/core"

function LabeledInput(props: { id: string; label: string; placeholder: string }) {
  return delegate(
    {
      focus: `${props.id}-input`, // Route focus() to the input
      value: `${props.id}-input`, // Route value property access
    },
    Box(
      { flexDirection: "row" },
      Text({ content: props.label }),
      Input({
        id: `${props.id}-input`,
        placeholder: props.placeholder,
        width: 20,
      }),
    ),
  )
}

const username = LabeledInput({ id: "username", label: "Username:", placeholder: "Enter username..." })

// This actually focuses the nested Input, not the outer Box
username.focus()

renderer.root.add(username)
```

### Delegate Mappings

The mapping object's keys are method or property names, and the values are descendant IDs:

```typescript
delegate(
  {
    focus: "inner-input", // .focus() -> find descendant "inner-input" and call focus()
    blur: "inner-input", // .blur() -> same
    add: "content-area", // .add() -> add children to "content-area" instead
    value: "inner-input", // .value get/set -> proxy to "inner-input"
  },
  vnode,
)
```

## Composing with Children

Custom constructs can accept and pass through children:

```typescript
function Card(props: { title: string }, ...children: VChild[]) {
  return Box(
    { border: true, padding: 1, flexDirection: "column" },
    Text({ content: props.title, fg: "#FFFF00" }),
    Box({ flexDirection: "column" }, ...children),
  )
}

renderer.root.add(Card({ title: "User Info" }, Text({ content: "Name: Alice" }), Text({ content: "Role: Admin" })))
```

## Mixing Renderables and Constructs

You can mix both approaches:

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

// Create a renderable directly
const container = new BoxRenderable(renderer, {
  id: "container",
  flexDirection: "column",
})

// Add constructs to it
container.add(Text({ content: "Title" }), Input({ placeholder: "Type here..." }))

renderer.root.add(container)
```

Or use constructs that contain renderables:

```typescript
const customRenderable = new CustomRenderable(renderer, { id: "custom" })

renderer.root.add(
  Box(
    { padding: 1 },
    Text({ content: "Header" }),
    customRenderable, // Regular renderable mixed in
    Text({ content: "Footer" }),
  ),
)
```

## Next Steps

See [Renderables vs Constructs](/docs/core-concepts/renderables-vs-constructs) for a detailed comparison of when to use each approach.
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