Components Overview

BetterTUI provides a rich set of terminal UI components. All components are imperative TypeScript classes that extend Box and integrate with the CliRenderer.

React adapter: A @bettertui/react adapter is planned. The JSX examples in this section will work once it ships. Today, use the vanilla @bettertui/core API.

Available Components

Component	Class	Description
Box	Box	Flexbox container — the building block for all layouts
Text	Text	Styled text with wrapping, truncation and rich markup
Input	Input	Single-line text input with cursor and validation events
Select	Select	Keyboard-navigable list selector with descriptions
TabSelect	TabSelect	Horizontal tab navigation widget
Slider	Slider	Horizontal or vertical range slider
ScrollBox	ScrollBox	Scrollable container with optional scroll bars
Canvas	Screen	Full-viewport layout with header / body / footer slots
Textarea	Textarea	Multi-line text editor
TextNode	TextNode	Composable styled-text node for rich inline markup

Planned Components (React adapter)

The following components are designed for @bettertui/react and will ship with the React adapter:

Component	Description
Button	Interactive button with focus and press states
Table	Data table with sorting and row selection
Tree	Hierarchical tree view with expand / collapse
Dialog	Modal overlay dialog

Basic Usage — vanilla TypeScript

import { Box, Text, createCliRenderer } from '@bettertui/core';

const renderer = await createCliRenderer({ exitOnCtrlC: true });

const container = new Box(renderer, {
  flexDirection: 'column',
  padding: 1,
  gap: 1,
});

const heading = new Text(renderer, { content: 'Hello, BetterTUI!', fg: '#7aa2f7' });
const body    = new Text(renderer, { content: 'Build fast terminal UIs.' });

container.add(heading);
container.add(body);
renderer.root.add(container);
renderer.start();

Component Tree

Every component is a Box (or a subclass). Components form a parent–child tree:

const root   = new Box(renderer, { flexDirection: 'column' });
const header = new Box(renderer, { height: 3, backgroundColor: '#1a1b26' });
const body   = new Box(renderer, { flexGrow: 1 });

root.add(header);
root.add(body);
renderer.root.add(root);

Shared Style Props

All components inherit BoxOptions and accept these layout / visual props:

Prop	Type	Description
width	number | string	Width in columns or '100%'
height	number | string	Height in rows or '100%'
flexDirection	'row' | 'column'	Main axis direction
flexGrow	number	Grow factor
flexShrink	number	Shrink factor
flexBasis	number | string	Base size
padding	number	Inner spacing
margin	number	Outer spacing
gap	number	Gap between children
border	boolean	Show border
borderStyle	string	'single' | 'double' | 'round' | 'thick' | 'dashed' | 'ascii'
borderColor	string	Border color
backgroundColor	string	Background color
opacity	number	0–1
visible	boolean	Show / hide the component
zIndex	number	Stack order

Focus Management

Focusable components (Input, Select, Slider, TabSelect, Textarea) expose .focus() / .blur():

input.focus();
input.on(InputEvents.ENTER, (value) => {
  console.log('Submitted:', value);
});