▚Box

A container component with borders, background colors, and layout capabilities. Use it to create panels, frames, and organized sections.

~/components/box

live

$ termino box-demo

border styles

┌ single ────┐

│single │

└────────────┘

╔ double ════╗

║double ║

╚════════════╝

╭ rounded ───╮

│rounded │

╰────────────╯

┏ heavy ━━━━━┓

┃heavy ┃

┗━━━━━━━━━━━━┛

flex row — cards with flexWrap: wrap

┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐

│ │ │ │ │ │

│ Feature 1 │ │ Feature 2 │ │ Feature 3 │

│ description of feature 1│ │ description of feature 2│ │ description of feature 3│

│ │ │ │ │ │

└──────────────────────┘ └──────────────────────┘ └──────────────────────┘

flex column — header / grow / footer

╭──────── settings ────────╮

│ header │

│┌ content area ┐ │

│ footer │

╰──────────────────────────╯

##Renderable API

tsrenderable

1import { BoxRenderable, createCliRenderer } from "@opentui/core"
2
3const renderer = await createCliRenderer()
4
5const panel = new BoxRenderable(renderer, {
6id: "panel",
7width: 30,
8height: 10,
9backgroundColor: "#333366",
10borderStyle: "double",
11borderColor: "#FFFFFF",
12})
13
14renderer.root.add(panel)

##Construct API

tsconstruct

1import { Box, Text, createCliRenderer } from "@opentui/core"
2
3const renderer = await createCliRenderer()
4
5renderer.root.add(
6Box(
7  {
8    width: 30,
9    height: 10,
10    backgroundColor: "#333366",
11    borderStyle: "rounded",
12  },
13  Text({ content: "Inside the box!" }),
14),
15)

##Border styles

1{ border: false }                  // no border
2{ border: true }                   // simple border
3{ borderStyle: "single" }          // ┌─┐ │ └─┘
4{ borderStyle: "double" }          // ╔═╗ ║ ╚═╝
5{ borderStyle: "rounded" }         // ╭─╮ │ ╰─╯
6{ borderStyle: "heavy" }           // ┏━┓ ┃ ┗━┛

##Titles

Add a title and bottom title to the box border:

1const panel = new BoxRenderable(renderer, {
2id: "settings",
3width: 40,
4height: 15,
5borderStyle: "rounded",
6title: "Settings",
7titleColor: "yellow",
8titleAlignment: "center",
9bottomTitle: "Footer",
10bottomTitleAlignment: "center",
11})

Title alignment controls placement of the title on the border:

1{ titleAlignment: "left" }    // ┌─ Title ────────┐
2{ titleAlignment: "center" }  // ┌──── Title ─────┐
3{ titleAlignment: "right" }   // ┌────────── Title ┐

##Layout container

Box works as a flex container for child elements:

1const container = Box(
2{
3  flexDirection: "column",
4  justifyContent: "space-between",
5  alignItems: "stretch",
6  width: 50,
7  height: 20,
8  padding: 1,
9  gap: 1,
10},
11Text({ content: "Header" }),
12Box({ flexGrow: 1, backgroundColor: "#222" }, Text({ content: "Content" })),
13Text({ content: "Footer" }),
14)

##Mouse events

Handle mouse interactions on the box:

1const button = new BoxRenderable(renderer, {
2id: "button",
3width: 12,
4height: 3,
5border: true,
6backgroundColor: "#444",
7onMouseDown: () => console.log("Button clicked!"),
8onMouseOver: () => { button.backgroundColor = "#666" },
9onMouseOut: () => { button.backgroundColor = "#444" },
10})

##Properties

properties

prop	type	default	description
width	number \| string	-	Width in characters or percentage
height	number \| string	-	Height in rows or percentage
backgroundColor	string \| RGBA	-	Background fill color
border	boolean	false	Show border
borderStyle	string	"single"	Border style
borderColor	string \| RGBA	-	Border color
title	string	-	Title text in border
titleColor	string \| RGBA	-	Color of the title text
titleAlignment	string	"left"	Title position
bottomTitle	string	-	Bottom title text
padding	number	0	Internal padding
gap	number \| string	-	Gap between children
flexDirection	string	"column"	Child layout direction
justifyContent	string	"flex-start"	Main axis alignment
alignItems	string	"stretch"	Cross axis alignment