input (Text Input)

A single-line or multi-line text input control with out-of-the-box keyboard navigation, word jumping, deletions, placeholder support, horizontal/vertical viewport auto-scrolling, custom formatting spans, and customizable carets.

Example Usage

type: input
id: searchInput
placeholder: 'Search documentation...'
placeholderStyle:
  fg: '#555555'
  italic: true
value: ''
caret:
  mode: invert
onChange: '@handlers.js:onSearchChange'
onSubmit: '@handlers.js:onSearchSubmit'

Intrinsic Properties

• value / text: string — The input's text content.
• cursor: number — 0-indexed character position of the caret (defaults to text length).
• placeholder: string — Displayed when value is empty.
• placeholderStyle: object — ANSI styling for the placeholder text (fg, bg, italic, bold).
• multiline: boolean — Single-line text field (false, default) or multi-line text area (true).
• wrap: boolean — Enables word wrapping and dynamic auto-growing height with height: content.
• maxHeight: number — Maximum height cap when auto-growing with height: content.
• submitMode: string — 'enter' (default: Enter submits, Shift+Enter/Alt+Enter inserts newline) or 'ctrl+enter' (Enter inserts newline, Ctrl+Enter submits).
• clearOnSubmit: boolean — Clears input content automatically upon submission (true, default).
• mask: string — Character mask for passwords or sensitive input (e.g. '*').
• maxLength: number — Maximum allowed string length.
• readOnly / disabled: boolean — Disables user keyboard input.
• caret: string | boolean | object — Caret definition or shorthand when focused (e.g. '█', '│', or { type: 'caret', mode: 'invert' }).
• unfocusedCaret: string | boolean | object — Optional standby caret definition rendered when the input is not focused (e.g. { char: '█', fg: '#565f89' }).
• format / onFormat: (text, cursor, ctx) => Array<{ text, fg, bg, bold, ... }> — Hook to transform raw text into custom styled spans.

Supported Keyboard Navigation

Supported Events

• Input Callbacks: onChange(ctx, { value, cursor, prevValue }), onSubmit(ctx, { value })
• Keyboard Input: onKeyPreview, onKey, onKeyBubble
• Focus Lifecycle: onFocus, onBlur