Skip to main content

​
Overview

The Theme class provides a declarative visual style system for Kraken TUI. Themes define default styles that cascade to all widgets in a subtree, unless overridden by explicit widget styles. Key features:
  • Global style defaults (colors, text decorations, borders, opacity)
  • Per-widget-type style overrides (e.g., all Input widgets use a specific color)
  • Built-in themes: Dark and Light
  • Custom theme creation
  • Theme binding to widget subtrees
Explicit widget styles always win over theme defaults (ADR-T12).

​
Creating Themes

​
create()

Create a new custom theme with empty defaults. 
static create(): Theme
​
Returns
Theme
A new theme instance.

​
dark()

Get a reference to the built-in dark theme. 
static dark(): Theme
​
Returns
Theme
The built-in dark theme (handle = 1).

​
light()

Get a reference to the built-in light theme. 
static light(): Theme
​
Returns
Theme
The built-in light theme (handle = 2).

​
destroy()

Destroy a custom theme and free its resources. Built-in themes (Dark, Light) cannot be destroyed. 
destroy(): void
Destroying a theme that is currently bound to widgets results in undefined behavior.

​
Global Style Defaults

These methods set style defaults that apply to all widgets in the themed subtree, unless overridden.

​
setForeground()

Set the default foreground (text) color. 
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 the default background color. 
setBackground(color: string | number): void
​
color
string | number
required
Color value (same format as setForeground).

​
setBorderColor()

Set the default border color. 
setBorderColor(color: string | number): void
​
color
string | number
required
Color value (same format as setForeground).

​
setBold()

Set the default bold text decoration. 
setBold(enabled: boolean): void
​
enabled
boolean
required
Whether bold is enabled by default.

​
setItalic()

Set the default italic text decoration. 
setItalic(enabled: boolean): void
​
enabled
boolean
required
Whether italic is enabled by default.

​
setUnderline()

Set the default underline text decoration. 
setUnderline(enabled: boolean): void
​
enabled
boolean
required
Whether underline is enabled by default.

​
setBorderStyle()

Set the default 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 the default opacity. 
setOpacity(value: number): void
​
value
number
required
Opacity value from 0.0 (fully transparent) to 1.0 (fully opaque).

​
Per-Widget-Type Defaults

These methods set style defaults for specific widget types (e.g., all Input widgets).

​
setTypeColor()

Set a color default for a specific widget type. 
setTypeColor(
  nodeType: "box" | "text" | "input" | "select" | "scrollBox" | "textarea" | number,
  prop: "fg" | "bg" | "borderColor",
  color: string | number
): void
​
nodeType
string | number
required
Widget type:
  • "box": Box container
  • "text": Text display
  • "input": Single-line input
  • "select": Select/dropdown
  • "scrollBox": Scrollable container
  • "textarea": Multi-line text area
  • number: Raw NodeType enum value
​
prop
'fg' | 'bg' | 'borderColor'
required
Color property:
  • "fg": Foreground (text) color
  • "bg": Background color
  • "borderColor": Border color
​
color
string | number
required
Color value (same format as global colors).

​
setTypeFlag()

Set a text decoration default for a specific widget type. 
setTypeFlag(
  nodeType: "box" | "text" | "input" | "select" | "scrollBox" | "textarea" | number,
  prop: "bold" | "italic" | "underline",
  enabled: boolean
): void
​
nodeType
string | number
required
Widget type (same as setTypeColor).
​
prop
'bold' | 'italic' | 'underline'
required
Text decoration property.
​
enabled
boolean
required
Whether the decoration is enabled.

​
setTypeBorderStyle()

Set a border style default for a specific widget type. 
setTypeBorderStyle(
  nodeType: "box" | "text" | "input" | "select" | "scrollBox" | "textarea" | number,
  style: "none" | "single" | "double" | "rounded" | "bold"
): void
​
nodeType
string | number
required
Widget type (same as setTypeColor).
​
style
'none' | 'single' | 'double' | 'rounded' | 'bold'
required
Border style (same as global border style).

​
setTypeOpacity()

Set an opacity default for a specific widget type. 
setTypeOpacity(
  nodeType: "box" | "text" | "input" | "select" | "scrollBox" | "textarea" | number,
  value: number
): void
​
nodeType
string | number
required
Widget type (same as setTypeColor).
​
value
number
required
Opacity value from 0.0 to 1.0.

​
Applying Themes

​
applyTo()

Apply this theme to a widget subtree. All descendants inherit the theme unless they have their own theme binding. 
applyTo(widget: Widget): void
​
widget
Widget
required
Widget to apply the theme to (and its descendants).

​
clearFrom()

Remove theme binding from a widget. The widget reverts to inheriting its parent’s theme. 
static clearFrom(widget: Widget): void
​
widget
Widget
required
Widget to clear the theme from.

​
Style Resolution Order

When a widget is rendered, styles are resolved in this priority order (highest to lowest):
  1. Explicit widget style (e.g., widget.setForeground("red"))
  2. Per-widget-type theme default (e.g., theme.setTypeColor("input", "fg", "blue"))
  3. Global theme default (e.g., theme.setForeground("white"))
  4. Built-in system default (terminal default colors)
const theme = Theme.create();
theme.setForeground("white");              // Global default: white
theme.setTypeColor("input", "fg", "blue"); // Input widgets: blue
theme.applyTo(rootWidget);

const input1 = new Input();
rootWidget.append(input1);
// input1 foreground: blue (per-type default)

const input2 = new Input();
input2.setForeground("red");               // Explicit override
rootWidget.append(input2);
// input2 foreground: red (explicit wins)

const text = new Text();
rootWidget.append(text);
// text foreground: white (global default)

​
Built-in Themes

​
Dark Theme

The built-in dark theme provides sensible defaults for dark terminal backgrounds. 
import { Theme } from "kraken-tui";

app.switchTheme(Theme.dark());
Characteristics:
  • Light text on dark backgrounds
  • Muted border colors
  • Handle: 1 (constant)

​
Light Theme

The built-in light theme provides sensible defaults for light terminal backgrounds. 
import { Theme } from "kraken-tui";

app.switchTheme(Theme.light());
Characteristics:
  • Dark text on light backgrounds
  • Visible border colors
  • Handle: 2 (constant)

​
Examples

​
Custom Theme

import { Theme, Kraken, Box, Text } from "kraken-tui";

const app = Kraken.init();

const theme = Theme.create();
theme.setForeground("#E0E0E0");
theme.setBackground("#121212");
theme.setBorderColor("#333333");
theme.setTypeBorderStyle("box", "rounded");
theme.setTypeColor("text", "fg", "#00FF00");

const root = new Box();
theme.applyTo(root);

const text = new Text();
text.setContent("Hello, Kraken!");
root.append(text);

app.setRoot(root);
app.render();

​
Theme Switching

let isDark = true;

app.run({
  onEvent: (event) => {
    if (event.type === "key" && event.key === "t") {
      isDark = !isDark;
      app.switchTheme(isDark ? Theme.dark() : Theme.light());
    }
  },
});

Build docs developers (and LLMs) love

Get started for freeTalk to us