Skip to main content

​
Overview

The Box widget is a flexible container that supports flexbox layout properties. It’s the primary building block for creating complex layouts in Kraken TUI.

​
Constructor

const box = new Box(options?: BoxOptions);

​
BoxOptions

​
width
string | number
Width of the box. Accepts:
  • Number: fixed width in cells
  • String: percentage (e.g., “50%”) or “auto”
​
height
string | number
Height of the box. Accepts:
  • Number: fixed height in cells
  • String: percentage (e.g., “100%”) or “auto”
​
flexDirection
string
Flex layout direction. Valid values:
  • "row" - horizontal layout (default)
  • "column" - vertical layout
  • "row-reverse" - horizontal, reversed
  • "column-reverse" - vertical, reversed
​
justifyContent
string
Main axis alignment. Valid values:
  • "flex-start" - align to start (default)
  • "flex-end" - align to end
  • "center" - center alignment
  • "space-between" - space between items
  • "space-around" - space around items
  • "space-evenly" - even spacing
​
alignItems
string
Cross axis alignment. Valid values:
  • "stretch" - stretch to fill (default)
  • "flex-start" - align to start
  • "flex-end" - align to end
  • "center" - center alignment
​
gap
number
Spacing between child elements in cells. Applies to both row and column gaps.
​
padding
number | [number, number, number, number]
Inner padding. Accepts:
  • Single number: applies to all sides
  • Array: [top, right, bottom, left]
​
border
string
Border style. Valid values:
  • "none" - no border (default)
  • "single" - single-line border
  • "double" - double-line border
  • "rounded" - rounded corners
  • "bold" - bold border
​
fg
string | number
Foreground (text) color. Accepts:
  • Hex string: "#FF0000"
  • Color name: "red", "blue", etc.
  • 256-color code: 196
​
bg
string | number
Background color. Same format as fg.

​
Example

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

const container = new Box({
  width: "100%",
  height: "50%",
  border: "rounded",
  padding: 2,
});

const label = new Text({ content: "Hello, World!" });
container.append(label);

​
Inherited Methods

Box inherits all methods from the Widget base class, including:
  • append(child) - Add child widgets
  • removeChild(child) - Remove child widgets
  • setVisible(visible) - Control visibility
  • destroy() - Clean up resources
  • animate(options) - Animate properties
See the Widget API reference for the complete list.

​
Notes

  • Box is the primary container widget for building layouts
  • Supports full flexbox layout model (direction, justify, align, gap)
  • Can nest boxes infinitely for complex layouts
  • All style properties can be set via constructor options or inherited Widget methods
  • Flexbox properties follow CSS Flexbox conventions

Build docs developers (and LLMs) love

Get started for freeTalk to us