cel-tui
    Preparing search index...

    Interface ContainerProps

    Styling props shared by all node types.

    Maps directly to terminal SGR (Select Graphic Rendition) attributes. Containers propagate their styles to descendants — child nodes inherit the nearest ancestor's values unless they set a value explicitly.

    interface ContainerProps {
        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;
        onClick?: () => void;
        onFocus?: () => void;
        onKeyPress?: KeyPressHandler;
        onScroll?: (offset: number, maxOffset: number) => void;
        overflow?: "hidden" | "scroll";
        padding?: { x?: number; y?: number };
        scrollbar?: boolean;
        scrollOffset?: number;
        scrollStep?: number;
        underline?: boolean;
        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? onClick? onFocus? onKeyPress? onScroll? overflow? padding? scrollbar? scrollOffset? scrollStep? underline? 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.

    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

    Called on key events that bubble up to this container. Keys are first handled by the focused element; unconsumed keys (e.g., non-editing shortcuts like "ctrl+s") bubble up through ancestors. The root container's onKeyPress acts as the global key handler.

    Return false to indicate the key was not consumed — it will continue bubbling to the next ancestor handler. Any other return value (undefined, true, or no return) means the key was consumed and bubbling stops. This is backward-compatible: existing void handlers consume by default.

    Key format: all lowercase, modifiers joined by + in canonical order ctrl+alt+shift+<key> (e.g., "ctrl+s", "alt+up", "escape"). The key string is a semantic identifier, not necessarily the exact inserted text — for example, uppercase A is reported as key "a".

    Normalized semantic key string.

    false to keep bubbling, anything else to consume.

    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).

    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.

    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