Widget - Kraken TUI

Overview

The Widget class is the abstract base for all UI components in Kraken TUI. It provides:

Layout methods: Width, height, padding, margin, gap
Style methods: Colors, text decorations, borders, opacity
Tree methods: Append, insert, remove children, destroy
Animation methods: Property animations, built-in effects (spinner, pulse, progress)
Focus methods: Make focusable, request focus
Accessibility methods: Roles, labels, descriptions

Widget is abstract. Instantiate concrete types like Box, Text, Input, Select, ScrollBox, or TextArea.

Properties

handle

number

required

Opaque native handle for FFI calls. Do not modify.

Tree Management

append()

Append a child widget to this widget’s children.

append(child: Widget): void

child

Widget

required

Widget to append.

insertChild()

Insert a child widget at a specific index. If index >= childCount, the child is appended.

insertChild(child: Widget, index: number): void

child

Widget

required

Widget to insert.

index

number

required

Zero-based index. If >= childCount, appends.

removeChild()

Remove a child widget from this widget’s children. Does not destroy the child.

removeChild(child: Widget): void

child

Widget

required

Widget to remove.

childCount()

Get the number of children.

childCount(): number

Returns

number

Number of direct children.

destroy()

Destroy this widget. Does not destroy children automatically.

destroy(): void

Accessing the widget after destruction results in undefined behavior.

destroySubtree()

Destroy this widget and all descendants in one native call. More efficient than recursive destroy.

destroySubtree(): void

Visibility

setVisible()

Set widget visibility. Invisible widgets are not rendered and do not participate in layout.

setVisible(visible: boolean): void

visible

boolean

required

Whether the widget is visible.

isVisible()

Check if the widget is visible.

isVisible(): boolean

Returns

boolean

true if visible, false otherwise.

markDirty()

Mark this widget as dirty, forcing a re-render on the next frame.

markDirty(): void

Layout Properties

setWidth()

Set the widget width.

setWidth(value: string | number): void

value

string | number

required

Width value:

number: Fixed width in columns
"<number>%": Percentage of parent
"auto": Auto-size to content

setHeight()

Set the widget height.

setHeight(value: string | number): void

value

string | number

required

Height value:

number: Fixed height in rows
"<number>%": Percentage of parent
"auto": Auto-size to content

setPadding()

Set inner spacing (padding) on all four sides.

setPadding(top: number, right: number, bottom: number, left: number): void

top

number

required

Top padding in rows.

right

number

required

Right padding in columns.

bottom

number

required

Bottom padding in rows.

left

number

required

Left padding in columns.

setMargin()

Set outer spacing (margin) on all four sides.

setMargin(top: number, right: number, bottom: number, left: number): void

top

number

required

Top margin in rows.

right

number

required

Right margin in columns.

bottom

number

required

Bottom margin in rows.

left

number

required

Left margin in columns.

setGap()

Set spacing between children in flex layouts.

setGap(rowGap: number, columnGap: number): void

rowGap

number

required

Gap between rows in rows.

columnGap

number

required

Gap between columns in columns.

Style Properties

setForeground()

Set text color (foreground).

setForeground(color: string | number): void

color

string | number

required

Color value:

"#RRGGBB": Hex RGB (24-bit true color)
"red", "blue", etc.: Named color
number: 256-color palette index (0-255)

setBackground()

Set background color.

setBackground(color: string | number): void

color

string | number

required

Color value (same format as setForeground).

setBold()

Enable or disable bold text.

setBold(enabled: boolean): void

enabled

boolean

required

Whether to enable bold.

setItalic()

Enable or disable italic text.

setItalic(enabled: boolean): void

enabled

boolean

required

Whether to enable italic.

setUnderline()

Enable or disable underline text decoration.

setUnderline(enabled: boolean): void

enabled

boolean

required

Whether to enable underline.

setBorderStyle()

Set the border style.

setBorderStyle(style: "none" | "single" | "double" | "rounded" | "bold"): void

style

'none' | 'single' | 'double' | 'rounded' | 'bold'

required

Border style:

"none": No border
"single": Single-line box drawing
"double": Double-line box drawing
"rounded": Rounded corners
"bold": Bold/thick lines

setOpacity()

Set widget opacity.

setOpacity(value: number): void

value

number

required

Opacity value from 0.0 (fully transparent) to 1.0 (fully opaque).

Animation

animate()

Animate a style property over time.

animate(options: {
  property: "opacity" | "fgColor" | "bgColor" | "borderColor" | "positionX" | "positionY";
  target: number | string;
  duration: number;
  easing?: "linear" | "easeIn" | "easeOut" | "easeInOut" | "cubicIn" | "cubicOut" | "elastic" | "bounce";
  loop?: boolean;
}): number

options.property

string

required

Property to animate:

"opacity": Widget opacity (0.0–1.0)
"fgColor": Foreground color
"bgColor": Background color
"borderColor": Border color
"positionX": Horizontal offset
"positionY": Vertical offset

options.target

number | string

required

Target value:

For opacity/position: number
For colors: string (hex/named) or number (palette index)

options.duration

number

required

Animation duration in milliseconds.

options.easing

string

default:"linear"

Easing function:

"linear": Constant speed
"easeIn": Slow start
"easeOut": Slow end
"easeInOut": Slow start and end
"cubicIn": Cubic ease-in
"cubicOut": Cubic ease-out
"elastic": Spring-like overshoot
"bounce": Bouncing effect

options.loop

boolean

default:"false"

If true, animation reverses and repeats indefinitely (oscillates).

Returns

number

Animation handle for cancellation or chaining.

cancelAnimation()

Cancel an active animation. The property retains its current value.

cancelAnimation(animHandle: number): void

animHandle

number

required

Animation handle returned by animate().

spinner()

Start a built-in spinner animation (cycles through braille frames).

spinner(options?: { interval?: number }): number

options.interval

number

default:"80"

Frame interval in milliseconds.

Returns

number

Animation handle for cancellation.

progress()

Start a built-in progress animation (opacity 0→1 over the given duration).

progress(options: {
  duration: number;
  easing?: "linear" | "easeIn" | "easeOut" | "easeInOut" | "cubicIn" | "cubicOut" | "elastic" | "bounce";
}): number

options.duration

number

required

Animation duration in milliseconds.

options.easing

string

default:"linear"

Easing function (same as animate).

Returns

number

Animation handle for cancellation.

pulse()

Start a built-in pulse animation (opacity oscillates indefinitely).

pulse(options: {
  duration: number;
  easing?: "linear" | "easeIn" | "easeOut" | "easeInOut" | "cubicIn" | "cubicOut" | "elastic" | "bounce";
}): number

options.duration

number

required

Duration of one oscillation cycle in milliseconds.

options.easing

string

default:"easeInOut"

Easing function (same as animate).

Returns

number

Animation handle for cancellation.

Focus

setFocusable()

Make this widget focusable or non-focusable.

setFocusable(focusable: boolean): void

focusable

boolean

required

Whether the widget can receive focus.

focus()

Request focus for this widget.

focus(): void

The widget must be focusable (setFocusable(true)).

Accessibility

setRole()

Set the accessibility role for this widget.

setRole(role: number): void

role

number

required

Accessibility role constant from AccessibilityRole enum.

setLabel()

Set the accessibility label (short description for screen readers).

setLabel(label: string): void

label

string

required

Label text.

setDescription()

Set the accessibility description (detailed description for screen readers).

setDescription(desc: string): void

desc

string

required

Description text.

Core API

Widgets

JSX & Reactivity

Reference

​Overview

​Properties

​Tree Management

​append()

​insertChild()

​removeChild()

​childCount()

​destroy()

​destroySubtree()

​Visibility

​setVisible()

​isVisible()

​markDirty()

​Layout Properties

​setWidth()

​setHeight()

​setPadding()

​setMargin()

​setGap()

​Style Properties

​setForeground()

​setBackground()

​setBold()

​setItalic()

​setUnderline()

​setBorderStyle()

​setOpacity()

​Animation

​animate()

​cancelAnimation()

​spinner()

​progress()

​pulse()

​Focus

​setFocusable()

​focus()

​Accessibility

​setRole()

​setLabel()

​setDescription()

Build docs developers (and LLMs) love

Overview

Properties

Tree Management

append()

insertChild()

removeChild()

childCount()

destroy()

destroySubtree()

Visibility

setVisible()

isVisible()

markDirty()

Layout Properties

setWidth()

setHeight()

setPadding()

setMargin()

setGap()

Style Properties

setForeground()

setBackground()

setBold()

setItalic()

setUnderline()

setBorderStyle()

setOpacity()

Animation

animate()

cancelAnimation()

spinner()

progress()

pulse()

Focus

setFocusable()

focus()

Accessibility

setRole()

setLabel()

setDescription()