cel-tui
    Preparing search index...

    Interface TextInputProps

    Props for the TextInput primitive.

    TextInput is a multi-line editable text container. It accepts container sizing props but has no children — its content is the value prop. Scroll is always framework-managed (follows cursor and responds to mouse wheel). Word-wrap is always on.

    When focused, TextInput consumes insertable text plus editing/navigation keys (arrows, backspace, delete, Enter, Tab), along with a small set of readline-style shortcuts: ctrl+a / ctrl+e, alt+b / alt+f, ctrl+left / ctrl+right, ctrl+w, and alt+d. Word movement and deletion use whitespace-delimited boundaries, and up / down follow visual wrapped lines. Other modifier combos and non-insertable control keys bubble to ancestor onKeyPress handlers.

    interface TextInputProps {
        alignItems?: "start" | "end" | "center" | "stretch";
        bgColor?: Color;
        bold?: boolean;
        fgColor?: Color;
        flex?: number;
        flexWrap?: "nowrap" | "wrap";
        focusable?: boolean;
        focused?: boolean;
        focusStyle?: StyleProps;
        gap?: number;
        height?: SizeValue;
        italic?: boolean;
        justifyContent?: "start" | "end" | "center" | "space-between";
        maxHeight?: number;
        maxWidth?: number;
        minHeight?: number;
        minWidth?: number;
        onBlur?: () => void;
        onChange: (value: string) => void;
        onClick?: () => void;
        onFocus?: () => void;
        onKeyPress?: KeyPressHandler;
        onScroll?: (offset: number, maxOffset: number) => void;
        overflow?: "hidden" | "scroll";
        padding?: { x?: number; y?: number };
        placeholder?: TextNode;
        scrollbar?: boolean;
        scrollOffset?: number;
        scrollStep?: number;
        underline?: boolean;
        value: string;
        width?: SizeValue;
    }

    Hierarchy (View Summary)

    Index

    Properties

    alignItems? bgColor? bold? fgColor? flex? flexWrap? focusable? focused? focusStyle? gap? height? italic? justifyContent? maxHeight? maxWidth? minHeight? minWidth? onBlur? onChange onClick? onFocus? onKeyPress? onScroll? overflow? padding? placeholder? scrollbar? scrollOffset? scrollStep? underline? value width?

    Properties

    alignItems?: "start" | "end" | "center" | "stretch"

    Align children along the cross axis.

    • VStack cross axis = horizontal
    • HStack cross axis = vertical
    bgColor?: Color

    Background color.

    bold?: boolean

    Render text with bold weight.

    fgColor?: Color

    Foreground (text) color.

    flex?: number

    Flex grow factor. Space remaining after fixed and intrinsic children is distributed proportionally among flex children.

    flex: 1  // equal share
    flex: 2  // double share
    flexWrap?: "nowrap" | "wrap"

    Whether children wrap to the next line when they exceed the container's main-axis size. Only meaningful on HStack.

    • "nowrap" (default) — all children on one line, may overflow.
    • "wrap" — children that exceed the width flow to the next row.

    When wrapping, each row is laid out independently: flex children distribute remaining space within their row, justifyContent applies per row, and alignItems applies per row. Rows are stacked vertically with gap spacing between them.

    focusable?: boolean

    Whether this container participates in focus traversal. Defaults to true when onClick is set. Set to false to make a container clickable by mouse but not reachable via Tab.

    focused?: boolean

    Whether this container is currently focused.

    When provided, focus is controlled — the app owns the state and must update this value via onFocus/onBlur. When omitted, focus is uncontrolled — the framework manages focus internally (Tab/Shift+Tab/Escape/click just work).

    focusStyle?: StyleProps

    Style overrides applied when this element is focused. Accepts any StyleProps — overridden values replace the element's normal styles and participate in inheritance.

    Works in both uncontrolled and controlled focus modes.

    { bgColor: "color06", fgColor: "color00" }  // reverse-video effect
    gap?: number

    Spacing between children in cells.

    height?: SizeValue

    Fixed height in cells, or percentage of parent height. When omitted, the container uses intrinsic sizing (fits content) or flex/percentage if those are set.

    italic?: boolean

    Render text in italic style.

    justifyContent?: "start" | "end" | "center" | "space-between"

    Distribute children along the main axis.

    • VStack main axis = vertical
    • HStack main axis = horizontal
    maxHeight?: number

    Maximum height constraint in cells.

    maxWidth?: number

    Maximum width constraint in cells.

    minHeight?: number

    Minimum height constraint in cells.

    minWidth?: number

    Minimum width constraint in cells.

    onBlur?: () => void

    Called when this container loses focus. In uncontrolled mode, this is a notification callback. In controlled mode, update focused here.

    onChange: (value: string) => void

    Called when the user edits text. Update the controlled value prop with the new string and call cel.render() to reflect the change.

    Type Declaration

      • (value: string): void

      • Parameters

        • value: string

          The new text content.

        Returns void

    onClick?: () => void

    Called on mouse click or Enter key when this container is focused. Setting this prop makes the container focusable by default.

    onFocus?: () => void

    Called when this container receives focus (Tab, Shift+Tab, or mouse click). In uncontrolled mode, this is a notification callback. In controlled mode, update focused here.

    onKeyPress?: KeyPressHandler

    Key handler that fires before the built-in editing logic. Return false to prevent the default editing action for that key (no character insertion, no cursor movement, no deletion). Any other return (or no return) lets the default action proceed.

    Receives the normalized semantic key string, not necessarily the exact inserted text. For example, typing uppercase A reports key "a" here while still inserting "A" into the input.

    // Enter submits instead of inserting a newline
    onKeyPress: (key) => {
      if (key === "enter") { handleSend(); return false; }
    }
    onScroll?: (offset: number, maxOffset: number) => void

    Called when the user scrolls this container (mouse wheel). In controlled mode, update scrollOffset with the new value to move the scroll position.

    Type Declaration

      • (offset: number, maxOffset: number): void

      • Parameters

        • offset: number

          The new scroll offset in cells.

        • maxOffset: number

          The maximum scroll offset (content size minus viewport size).

        Returns void

    overflow?: "hidden" | "scroll"

    Content overflow behavior.

    • "hidden" (default) — clip content at the container edge.
    • "scroll" — enable scrolling along the main axis.
    padding?: { x?: number; y?: number }

    Internal padding in cells. x adds horizontal padding (left + right), y adds vertical (top + bottom).

    placeholder?: TextNode

    A TextNode displayed when value is empty. Fully stylable — pass a Text() call with any styling props.

    placeholder: Text("type a message...", { fgColor: "color08" })
    scrollbar?: boolean

    Show a scrollbar indicator when overflow is "scroll".

    scrollOffset?: number

    Controlled scroll position in cells. When provided, the app owns scroll state and must update this value via onScroll. When omitted, scroll is framework-managed (uncontrolled).

    scrollStep?: number

    Mouse wheel step size in cells along the container's main axis. When omitted, the framework uses an adaptive default based on the scroll target's viewport size: floor(viewportMainAxis / 3), clamped to the range 3..8.

    Affects mouse wheel input only — not programmatic scrollOffset updates or TextInput cursor-follow behavior.

    underline?: boolean

    Render text with an underline.

    value: string

    Current text content. Controlled — the app owns this value.

    width?: SizeValue

    Fixed width in cells, or percentage of parent width. When omitted, the container uses intrinsic sizing (fits content) or flex/percentage if those are set.

    Settings

    Member Visibility

    On This Page

    Properties