PyModel/pythinker-code / .agents/skills/opentui
opentui
VerifiedBuild terminal UIs with OpenTUI. Covers core, components, audio, keymaps, React, Solid, plugins, testing, standalone executables, QR encoding, SSH, and Three.js WebGPU.
docs/components/textarea.mdx
View on GitHub---
title: Textarea
description: Multi-line text input with selection and keybindings
order: 4
---
# Textarea
Multi-line text input with cursor, selection, and rich keybindings.
## Basic usage
### Renderable API
```typescript
import { TextareaRenderable, createCliRenderer } from "@opentui/core"
const renderer = await createCliRenderer()
const textarea = new TextareaRenderable(renderer, {
id: "notes",
width: 50,
height: 6,
placeholder: "Type notes here...",
backgroundColor: "#1a1a1a",
focusedBackgroundColor: "#222222",
textColor: "#FFFFFF",
cursorColor: "#00FF88",
})
renderer.root.add(textarea)
textarea.focus()
```
## Submit handling
Bind a submit action and listen for `onSubmit`:
```typescript
import { TextareaRenderable } from "@opentui/core"
const textarea = new TextareaRenderable(renderer, {
width: 50,
height: 6,
onSubmit: () => {
console.log("Submitted:", textarea.plainText)
},
keyBindings: [{ name: "return", ctrl: true, action: "submit" }],
})
```
## Placeholder styling
```typescript
const textarea = new TextareaRenderable(renderer, {
width: 40,
height: 4,
placeholder: "Type here",
placeholderColor: "#666666",
})
```
## Construct API
> Not available yet. Use `TextareaRenderable` for now.
## Properties
| Property | Type | Default | Description |
| ------------------------ | ------------------------------------- | ----------- | --------------------------------- |
| `width` | `number` or `string` | - | Width in characters or percentage |
| `height` | `number` or `string` | - | Height in rows or percentage |
| `initialValue` | `string` | `""` | Initial text content |
| `placeholder` | `string`, `StyledText`, or `null` | `null` | Placeholder content |
| `placeholderColor` | `string` or `RGBA` | `#666666` | Placeholder color |
| `backgroundColor` | `string` or `RGBA` | transparent | Background when unfocused |
| `textColor` | `string` or `RGBA` | `#FFFFFF` | Text color when unfocused |
| `focusedBackgroundColor` | `string` or `RGBA` | transparent | Background when focused |
| `focusedTextColor` | `string` or `RGBA` | `#FFFFFF` | Text color when focused |
| `wrapMode` | `"none"`, `"char"`, or `"word"` | `"word"` | Line wrapping mode |
| `selectionBg` | `string` or `RGBA` | - | Selection background |
| `selectionFg` | `string` or `RGBA` | - | Selection foreground |
| `cursorColor` | `string` or `RGBA` | `#FFFFFF` | Cursor color |
| `cursorStyle` | `CursorStyleOptions` | - | Cursor style and blinking |
| `keyBindings` | `KeyBinding[]` | - | Custom keybindings |
| `keyAliasMap` | `Record<string, string>` | - | Key alias mapping |
| `onSubmit` | `(event: SubmitEvent) => void` | - | Submit handler |
| `onContentChange` | `(event: ContentChangeEvent) => void` | - | Fired on content changes |
| `onCursorChange` | `(event: CursorChangeEvent) => void` | - | Fired on cursor movement |
## Useful properties
| Property | Type | Description |
| ----------------------- | -------------------------- | --------------------------------------------------------------- |
| `plainText` | `string` | Current text content |
| `cursorOffset` | `number` | Cursor offset in the buffer |
| `cursorCharacterOffset` | `number \| undefined` | Offset of the character under the cursor (skips trailing blank) |
| `logicalCursor` | `{ row, col }` | Logical line/column of the cursor |
| `visualCursor` | `{ row, col, visualLine }` | Visual (post-wrap) cursor position |
| `traits` | `EditorTraits` | Editor traits published to hosting UI (see [Traits](#traits)) |
## Cursor and selection control
`TextareaRenderable` (and its base `EditBufferRenderable`) exposes a programmatic API. You can move the cursor, edit text, and drive selections from your own keybindings or commands. All selection-aware movement methods accept `{ select: true }` to extend the current selection instead of moving the cursor.
### Cursor movement
```typescript
textarea.setCursor(row, col)
textarea.moveCursorLeft()
textarea.moveCursorRight({ select: true })
textarea.moveCursorUp()
textarea.moveCursorDown()
textarea.moveWordForward({ select: true })
textarea.moveWordBackward()
textarea.gotoLine(0)
textarea.gotoLineStart()
textarea.gotoLineTextEnd()
textarea.gotoLineHome({ select: true }) // Emacs-style smart home
textarea.gotoLineEnd()
textarea.gotoVisualLineHome()
textarea.gotoVisualLineEnd()
textarea.gotoBufferHome()
textarea.gotoBufferEnd({ select: true })
```
### Selection
```typescript
textarea.setSelection(start, end) // half-open offsets
textarea.setSelectionInclusive(start, end) // inclusive end
textarea.selectAll()
textarea.clearSelection()
textarea.deleteSelection()
```
### Editing
```typescript
textarea.insertChar("a")
textarea.insertText("\ninserted")
textarea.deleteChar() // forward delete
textarea.deleteCharBackward() // backspace
textarea.deleteWordForward()
textarea.deleteWordBackward()
textarea.deleteToLineEnd()
textarea.deleteToLineStart()
textarea.deleteLine()
textarea.newLine()
textarea.undo()
textarea.redo()
```
These methods update the cursor, clear any active global selection, and call `requestRender()` for you.
## Traits
The `traits` property lets an editor advertise intent to a host UI — which built-in keys it wants to capture, whether it wants the chrome to visually suspend, and a short status label for a footer or status bar. Assigning a new `EditorTraits` object emits the `traits-changed` event when the value differs from the previous one.
```typescript
import { EditBufferRenderableEvents, type EditorTraits } from "@opentui/core"
textarea.traits = {
capture: ["escape", "submit"], // consume these before host binds
suspend: false,
status: "Composing reply",
} satisfies EditorTraits
textarea.on(EditBufferRenderableEvents.TRAITS_CHANGED, (traits) => {
updateFooter(traits.status ?? "")
})
```
| Field | Type | Description |
| --------- | ----------------- | ------------------------------------------------------------------------------- |
| `capture` | `EditorCapture[]` | Keys the editor wants to capture: `"escape"`, `"navigate"`, `"submit"`, `"tab"` |
| `suspend` | `boolean` | Hint to the host to suspend ambient UI (dim borders, hide hints, etc.) |
| `status` | `string` | Optional short label surfacing editor mode in a status bar |
Traits reset to an empty object when you destroy the renderable. Use `isEditBufferRenderable(renderable)` if you need to distinguish editor renderables from plain text renderables in a generic tree.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |