Element Reference

Overview

Element is the building block of go-tui UIs. Every visible piece of content (text, borders, containers, scrollable regions) is an Element. Elements form a tree: a root element contains children, which contain their own children, and so on. The layout engine computes positions using CSS flexbox, and the renderer draws the result to a character buffer.

You can create elements two ways: in .gsx templates (the common path) or programmatically with tui.New().

// In .gsx — the compiler turns this into tui.New(...) calls
<div class="flex-col gap-1 p-1 border-rounded">
    <span class="font-bold text-cyan">Hello</span>
    <span>World</span>
</div>

// Programmatic equivalent
root := tui.New(
    tui.WithDirection(tui.Column),
    tui.WithGap(1),
    tui.WithPadding(1),
    tui.WithBorder(tui.BorderRounded),
)
title := tui.New(
    tui.WithText("Hello"),
    tui.WithTextStyle(tui.NewStyle().Bold().Foreground(tui.ANSIColor(tui.Cyan))),
)
body := tui.New(tui.WithText("World"))
root.AddChild(title, body)

Element implements the Viewable, Focusable, and Layoutable interfaces.

Creating Elements

New

func New(opts ...Option) *Element

Creates a new Element with the given options. By default, elements use Auto width and height, Row direction, and a transparent background, with border and text unset.

box := tui.New(
    tui.WithWidth(40),
    tui.WithHeight(10),
    tui.WithBorder(tui.BorderRounded),
    tui.WithText("Content"),
)

In .gsx files, elements are created with HTML-like tags:

<div width={40} height={10} border={tui.BorderRounded}>
    <span>Content</span>
</div>

Option Functions

Option is defined as func(*Element). Pass options to tui.New() to configure an element at creation time. The .gsx compiler translates element attributes and Tailwind classes into these same option calls.

Dimensions

// Fixed 40x10 box
tui.New(tui.WithSize(40, 10))

// Half-width panel with minimum
tui.New(tui.WithWidthPercent(50), tui.WithMinWidth(20))

Flex Container

These options control how an element lays out its children.

// Vertical layout with centered children and 1-cell gap
tui.New(
    tui.WithDirection(tui.Column),
    tui.WithAlign(tui.AlignCenter),
    tui.WithGap(1),
)

Flex Item

These options control how an element behaves as a child within a flex container.

// Sidebar (fixed) + main content (grows to fill)
sidebar := tui.New(tui.WithWidth(30))
content := tui.New(tui.WithFlexGrow(1))

Spacing

// 1-cell padding all around, 2-cell top margin
tui.New(
    tui.WithPadding(1),
    tui.WithMarginTRBL(2, 0, 0, 0),
)

Visual

// Cyan-bordered box with bold white text on a blue background
tui.New(
    tui.WithBorder(tui.BorderRounded),
    tui.WithBorderStyle(tui.NewStyle().Foreground(tui.ANSIColor(tui.Cyan))),
    tui.WithBackground(tui.NewStyle().Background(tui.ANSIColor(tui.Blue))),
    tui.WithText("Status: OK"),
    tui.WithTextStyle(tui.NewStyle().Bold().Foreground(tui.ANSIColor(tui.White))),
)

When WithFocusBorderStyle is set, the border switches to it while the element holds focus and returns to WithBorderStyle on blur. A title set with WithBorderTitleStyle follows the same focus-aware color unless you give the title its own style.

Gradient

tui.New(
    tui.WithText("Rainbow"),
    tui.WithTextGradient(tui.NewGradient(
        tui.ANSIColor(tui.Red),
        tui.ANSIColor(tui.Cyan),
    )),
)

Focus

tui.New(
    tui.WithFocusable(true),
    tui.WithOnFocus(func(el *tui.Element) {
        el.SetBorderStyle(tui.NewStyle().Foreground(tui.ANSIColor(tui.Cyan)))
    }),
    tui.WithOnBlur(func(el *tui.Element) {
        el.SetBorderStyle(tui.NewStyle())
    }),
)

Scroll

tui.New(
    tui.WithScrollable(tui.ScrollVertical),
    tui.WithScrollOffset(0, scrollY.Get()),
    tui.WithScrollbarThumbStyle(tui.NewStyle().Foreground(tui.ANSIColor(tui.Cyan))),
)

Behavior

// Truncated text in a fixed-width cell
tui.New(
    tui.WithWidth(20),
    tui.WithText("This is a very long string that will be truncated"),
    tui.WithTruncate(true),
)

Accessors

Get and set methods for reading and modifying element properties after creation. Setters that affect layout or rendering call MarkDirty() automatically.

Style (Layout)

func (e *Element) Style() LayoutStyle
func (e *Element) SetStyle(style LayoutStyle)

Read or replace the full layout style. SetStyle marks the element dirty.

Dimensions

func (e *Element) SetWidth(v Value)
func (e *Element) SetHeight(v Value)

Change an element's width or height after creation. Both mark the element and its ancestors dirty so layout recomputes on the next frame. Pass tui.Fixed(n), tui.Percent(p), or tui.Auto().

These apply to retained elements you hold across renders, such as a cached component's root. A setter on an element that the render rebuilds each frame has no lasting effect, since the next render recreates it from its options.

// Grow a results dropdown to fit its matches, capped at 8 rows
dropdown.SetHeight(tui.Fixed(min(len(matches), 8)))

Border

func (e *Element) Border() BorderStyle
func (e *Element) SetBorder(border BorderStyle)
func (e *Element) BorderStyle() Style
func (e *Element) SetBorderStyle(style Style)
func (e *Element) BorderTitle() string
func (e *Element) SetBorderTitle(title string)
func (e *Element) BorderTitleAlign() TextAlign
func (e *Element) SetBorderTitleAlign(align TextAlign)
func (e *Element) BorderTitleStyle() *Style
func (e *Element) SetBorderTitleStyle(style *Style)
func (e *Element) FocusBorderStyle() *Style
func (e *Element) SetFocusBorderStyle(style *Style)

Border() returns the border shape (BorderSingle, BorderRounded, etc.). BorderStyle() returns the color/attribute style used to draw the border lines. BorderTitle() returns the title text drawn in the top border, or "" when no title is set.

BorderTitleAlign() reports where the title sits on the top border, TextAlignCenter by default. BorderTitleStyle() and FocusBorderStyle() return nil when no override is set, so the title uses the active border style and the border keeps its base style while focused. Pass nil to either setter to clear the override.

Background

func (e *Element) Background() *Style
func (e *Element) SetBackground(style *Style)

Returns nil when the background is transparent. Pass nil to SetBackground to make it transparent again.

Text

func (e *Element) Text() string
func (e *Element) SetText(content string)
func (e *Element) TextStyle() Style
func (e *Element) SetTextStyle(style Style)
func (e *Element) TextAlign() TextAlign
func (e *Element) SetTextAlign(align TextAlign)

SetText marks the element dirty. SetTextStyle prevents style inheritance from the parent element for this element's text.

Truncate

func (e *Element) Truncate() bool
func (e *Element) SetTruncate(truncate bool)

When enabled, text that overflows the element's content width is cut off with an ellipsis character (…).

Hidden

func (e *Element) Hidden() bool
func (e *Element) SetHidden(hidden bool)

Hidden elements are excluded from both layout and rendering. Their children are also skipped.

Overflow

func (e *Element) Overflow() OverflowMode
func (e *Element) SetOverflow(mode OverflowMode)

Controls whether content that exceeds element bounds is visible or clipped.

Tree Methods

Elements form a tree. These methods manipulate the parent-child relationships.

AddChild

func (e *Element) AddChild(children ...*Element)

Appends one or more children. Each child's parent is set to this element, and the element is marked dirty. If the root element has callback hooks registered (for focus or child-added notifications), they fire for each new child.

container := tui.New(tui.WithDirection(tui.Column))
container.AddChild(
    tui.New(tui.WithText("First")),
    tui.New(tui.WithText("Second")),
)

RemoveChild

func (e *Element) RemoveChild(child *Element) bool

Removes a specific child. Returns true if the child was found and removed. The removed child's parent is set to nil.

RemoveAllChildren

func (e *Element) RemoveAllChildren()

Removes all children from this element.

Children

func (e *Element) Children() []*Element

Returns the slice of child elements.

Parent

func (e *Element) Parent() *Element

Returns the parent element, or nil for the root.

SetOnChildAdded

func (e *Element) SetOnChildAdded(fn func(*Element))

Registers a callback that fires whenever a descendant is added anywhere in this element's subtree. Used internally by the framework for focus management.

Layout Methods

The layout engine uses these methods during the flexbox calculation pass.

LayoutStyle / LayoutChildren

func (e *Element) LayoutStyle() LayoutStyle
func (e *Element) LayoutChildren() []Layoutable

Part of the Layoutable interface. LayoutStyle returns the element's style with border padding added (borders consume 1 cell on each side). LayoutChildren returns visible children only; hidden elements are excluded.

SetLayout / GetLayout

func (e *Element) SetLayout(l LayoutResult)
func (e *Element) GetLayout() LayoutResult

Called by the layout engine to store and retrieve computed layout results.

Calculate

func (e *Element) Calculate(availableWidth, availableHeight int)

Runs the flexbox layout algorithm on this element and all its descendants. Wraps the package-level tui.Calculate() function.

root.Calculate(80, 24) // Layout for an 80x24 terminal

Rect / ContentRect

func (e *Element) Rect() Rect
func (e *Element) ContentRect() Rect

Rect returns the border box (the full area including border and padding). ContentRect returns the inner content area (inside border and padding). Both are populated after Calculate runs.

IntrinsicSize

func (e *Element) IntrinsicSize() (width, height int)

Returns the natural content-based dimensions. For text elements, this is the text width plus padding and border. For containers, it's computed from children. Scrollable elements return (0, 0) since they rely on explicit sizing or flexGrow. Horizontal rules return (0, 1).

Dirty Flags

func (e *Element) IsDirty() bool
func (e *Element) SetDirty(dirty bool)
func (e *Element) MarkDirty()

MarkDirty walks up the parent chain setting dirty flags, and also marks the owning App as dirty (triggering a re-render on the next frame). IsDirty and SetDirty are used by the layout engine.

IsHR

func (e *Element) IsHR() bool

Returns true if this element was configured with WithHR().

Focus Methods

Focus determines which element receives keyboard input.

Query

func (e *Element) IsFocusable() bool
func (e *Element) IsFocused() bool
func (e *Element) SetFocusable(focusable bool)

Check or change whether an element can receive focus, and whether it currently has it.

Focus / Blur

func (e *Element) Focus()
func (e *Element) Blur()

Focus marks the element as focused and calls the onFocus callback if one is registered. Blur clears the focused state and calls onBlur. These don't cascade to children. Only the target element is affected.

SetOnFocus / SetOnBlur

func (e *Element) SetOnFocus(fn func(*Element))
func (e *Element) SetOnBlur(fn func(*Element))

Register focus/blur callbacks after creation. Both implicitly set focusable = true.

HandleEvent

func (e *Element) HandleEvent(event Event) bool

Dispatches an event to this element. For scrollable elements, handles arrow keys, Page Up/Down, Home/End, and mouse wheel events. Returns true if the event was consumed.

Built-in scroll key handling:

• Up/Down arrows: scroll vertically by 1 row
• Left/Right arrows: scroll horizontally by 1 column
• Page Up/Page Down: scroll by viewport height
• Home: scroll to top-left
• End: scroll to bottom
• Mouse wheel: scroll vertically by 1 row per tick

ContainsPoint

func (e *Element) ContainsPoint(x, y int) bool

Returns true if the point falls within the element's computed layout bounds. Useful for hit testing in HandleMouse implementations.

Scroll Methods

Scroll methods only work on elements created with WithScrollable().

Query

func (e *Element) IsScrollable() bool
func (e *Element) ScrollModeValue() ScrollMode
func (e *Element) ScrollOffset() (x, y int)
func (e *Element) ContentSize() (width, height int)
func (e *Element) ViewportSize() (width, height int)
func (e *Element) MaxScroll() (maxX, maxY int)

Control

func (e *Element) ScrollTo(x, y int)
func (e *Element) ScrollBy(dx, dy int)
func (e *Element) ScrollToTop()
func (e *Element) ScrollToBottom()

ScrollTo sets an absolute position, clamped to valid range. ScrollBy adjusts relative to the current position. ScrollToBottom scrolls immediately and also sets a pending flag so that after the next layout pass (when content size may have changed), it re-scrolls to the new bottom. This makes it reliable for following new content.

IsAtBottom

func (e *Element) IsAtBottom() bool

Returns true if the element is scrolled to the bottom. Useful for implementing sticky-scroll behavior (auto-follow new content, but stop following when the user scrolls up).

ScrollIntoView

func (e *Element) ScrollIntoView(child *Element)

Scrolls the minimum amount needed to make child fully visible within this element's viewport. Does nothing if child is not a descendant or if scrolling is disabled.

Watcher and Discovery Methods

Background operations (timers, channel watchers) and tree traversal hooks.

Watchers

func (e *Element) AddWatcher(w Watcher)
func (e *Element) Watchers() []Watcher
func (e *Element) WalkWatchers(fn func(Watcher))

AddWatcher attaches a timer or channel watcher to this element. Watchers start automatically when the element tree is set as the app root. WalkWatchers traverses the tree and calls fn for every watcher (skipping hidden elements).

Focus Discovery

func (e *Element) WalkFocusables(fn func(Focusable))
func (e *Element) SetOnFocusableAdded(fn func(Focusable))

WalkFocusables does a depth-first walk calling fn for each focusable element. SetOnFocusableAdded registers a callback for when new focusable descendants are added. Both are used by the App for automatic focus management.

Pre-Render Hook

func (e *Element) SetOnUpdate(fn func())

Sets a function called before each render pass. Useful for polling, animations, or other per-frame logic.

Hit Testing

func (e *Element) ElementAt(x, y int) *Element
func (e *Element) ElementAtPoint(x, y int) Focusable

ElementAt finds the deepest element containing the given point. Children are checked in reverse order (last child renders on top, so it gets priority). Returns nil if no element contains the point.

ElementAtPoint does the same thing but returns a Focusable interface to satisfy the internal mouse hit-testing contract.

Cursor Reporting

The App drives the real terminal cursor. At the end of each frame it asks the focused element where the cursor belongs and moves the hardware cursor there, so the cursor blinks and behaves natively instead of being painted into the buffer.

func WithCursorSource(fn func() (col, row int, visible bool)) Option
func (e *Element) SetCursorSource(fn func() (col, row int, visible bool))
func (e *Element) ReportCursor() (col, row int, visible bool)

An element reports its cursor by installing a source, either with WithCursorSource at creation or SetCursorSource afterward. The source returns the cursor position in display cells measured from the element's content origin, plus whether it is visible. The framework converts that to an absolute terminal cell, accounting for the scroll offset and any clipping ancestor.

Input and TextArea install a source on their own, so a focused text widget places the real cursor with no extra wiring. To take over cursor placement yourself, or to suppress it, build the App with WithManualCursor() (see the App Reference).

type CursorReporter interface {
    ReportCursor() (col, row int, visible bool)
}

Element implements CursorReporter. ReportCursor returns the absolute cell captured during the most recent render. It reports visible == false when no source is set, when the source reports invisible, or when the cursor was clipped out of view.

Rendering

func (e *Element) Render(buf *Buffer, width, height int)

The main rendering entry point. Runs layout (if dirty) and then renders the full element tree to the buffer.

func RenderTree(buf *Buffer, root *Element)

Package-level function that traverses the element tree and draws each element to the buffer. Handles background fills, borders, text, gradients, scroll clipping, and overflow clipping. Called by Element.Render() after layout.

Enums

TextAlign

Controls horizontal text alignment within an element's content area.

Text alignment only takes effect when the element is wider than its text content, e.g. when you set an explicit WithWidth larger than the text. For auto-sized elements, the text fills the element exactly, and the parent's AlignItems handles positioning.

ScrollMode

Controls which directions an element can scroll.

OverflowMode

Controls how content beyond element bounds is handled.