typography.md

title	Typography Components

Typography Components

Text

Rich inline text with bold, italic, color, and dimming support.

Props:

Prop	Type	Default	Required
children	ReactNode	—	✓
bold	boolean	—	—
italic	boolean	—	—
color	string	—	—
dimColor	boolean	—	—
underline	boolean	—	—
strikethrough	boolean	—	—
wrap	`'wrap'	'truncate'	'truncate-end'`

Usage:

import { Text } from 'termui/components';

<Text bold color="cyan">
  Hello, world!
</Text>;

---

Heading

Section heading with h1–h4 levels and optional figlet ASCII art.

Props:

Prop	Type	Default	Required
children	string	—	✓
level	`1	2	3
ascii	boolean	false	—
font	string	'Standard'	—
color	string	—	—

Usage:

import { Heading } from 'termui/components'

<Heading level={1} color="cyan">My CLI Tool</Heading>
<Heading level={1} ascii font="Big">TITLE</Heading>

---

Code

Syntax-highlighted code block with 50+ language support.

Props:

Prop	Type	Default	Required
children	string	—	✓
language	string	'text'	—
showLineNumbers	boolean	false	—
theme	string	'auto'	—

Usage:

import { Code } from 'termui/components';

<Code language="typescript">{'const x: number = 42;'}</Code>;

---

Link

Clickable hyperlink using OSC 8 terminal hyperlink protocol.

Props:

Prop	Type	Default	Required
href	string	—	✓
children	ReactNode	—	✓
color	string	—	—

Usage:

import { Link } from 'termui/components';

<Link href="https://termui.dev" color="cyan">
  termui.dev
</Link>;

---

Badge

Semantic status badge with color presets.

Props:

Prop	Type	Default	Required
children	ReactNode	—	✓
variant	`'default'	'success'	'warning'
color	string	—	—

Usage:

import { Badge } from 'termui/components'

<Badge variant="success">Deployed</Badge>
<Badge variant="error">Failed</Badge>

---

Tag

Removable chip/tag with optional close callback.

Props:

Prop	Type	Default	Required
children	ReactNode	—	✓
onRemove	() => void	—	—
color	string	—	—

Usage:

import { Tag } from 'termui/components';

<Tag onRemove={() => remove('typescript')}>typescript</Tag>;

---

Markdown

Full Markdown renderer — headings, bold, italic, code, lists, links.

Props:

Prop	Type	Default	Required
children	string	—	✓
theme	MarkdownTheme	—	—

Usage:

import { Markdown } from 'termui/components';

<Markdown>{'# Hello\n\nThis is **bold** text.'}</Markdown>;

---

JSON

Pretty-print JSON with syntax coloring and collapsible nodes.

Props:

Prop	Type	Default	Required
value	unknown	—	✓
indent	number	2	—
collapsed	boolean	false	—

Usage:

import { JSONView } from 'termui/components';

<JSONView value={{ name: 'Alice', age: 30 }} />;

---

Gradient

Renders text with a smooth color gradient.

Props:

Prop	Type	Default	Required
children	string	—	✓
colors	string[]	—	✓

Usage:

import { Gradient } from 'termui/components';

<Gradient colors={['#ff6b6b', '#4ecdc4']}>Gradient Text</Gradient>;

---

BigText

Renders large ASCII-art block-letter text. Ships two render engines:

Engine	When to use	Install	Bundle cost
'basic' (default)	Most apps. Single color, uppercase A–Z, digits, basic punctuation.	None — built in.	0 KB extra
'cfonts' (opt-in)	You want richer fonts, gradients, alignment, or backgrounds.	npm install cfonts	~400 KB

If you ask for engine="cfonts" but cfonts isn't installed, BigText logs a one-line warning and falls back to the basic engine so the UI never breaks.

Quick start:

import { BigText } from 'termui/components';

// Default — zero deps
<BigText>HELLO</BigText>

// Color (basic or cfonts)
<BigText color="cyan">HELLO</BigText>

// Opt in to cfonts for a richer look
<BigText engine="cfonts" font="tiny">HELLO</BigText>

// Gradient across characters (cfonts only)
<BigText engine="cfonts" font="tiny" gradient={['red', 'magenta']} transitionGradient>
  TERMUI
</BigText>

// Hex color + centered (cfonts only — basic engine ignores align)
<BigText engine="cfonts" font="3d" color="#ff6b35" align="center">MyApp</BigText>

Installing the cfonts engine in a shadcn-style project:

npx termui add big-text   # copies BigText.tsx + BigText.font.ts (basic engine)
npm install cfonts        # opt in to engine="cfonts" — only needed for richer fonts

Props:

Prop	Type	Default	Engine	Required
children	string	—	both	✓
engine	'basic' | 'cfonts'	'basic'	both	—
color	string | string[]	theme primary	both (basic uses first)	—
font	'console' | 'block' | 'simpleBlock' | 'simple' | '3d' | 'simple3d' | 'chrome' | 'huge' | 'shade' | 'slick' | 'grid' | 'pallet' | 'tiny'	'block'	cfonts only	—
gradient	[string, string]	—	cfonts only	—
transitionGradient	boolean	false	cfonts only	—
background	string	—	cfonts only	—
align	'left' | 'center' | 'right'	'left'	cfonts only	—
letterSpacing	number	—	cfonts only	—
lineHeight	number	—	cfonts only	—
space	boolean	false	cfonts only	—

Props marked cfonts only are silently ignored under the basic engine.

Migrating from BigText 1.x:

• The pre-1.x font="Standard" / font="Big" figlet names no longer exist. Use engine="cfonts" and pick from the list above (e.g. font="block", font="tiny").
• The SplashScreen.titleColorAlt prop's behaviour now depends on engine: under 'cfonts' it forms a smooth gradient across glyphs; under 'basic' it renders the legacy alternating-row striped look.

---

Digits

Renders numbers using box-drawing characters.

Props:

Prop	Type	Default	Required
value	`number	string`	—
color	string	—	—
size	number	1	—

Usage:

import { Digits } from 'termui/components';

<Digits value={42} color="green" />;

---

StreamingText

Renders text that arrives incrementally — from an AsyncIterable<string> stream or via a typing animation. Shows a blinking ▌ cursor while streaming.

Props:

Prop	Type	Default	Description
text	string	—	Controlled text (static or with animate)
stream	AsyncIterable<string>	—	Live token stream; component manages state internally
cursor	boolean	true	Show blinking ▌ cursor while streaming
animate	boolean	false	Typing animation for pre-buffered text
speed	number	30	Typing speed in ms per character
onComplete	(text: string) => void	—	Called when streaming or animation completes
cursorColor	string	theme primary	Cursor color

Usage — typing animation:

import { StreamingText } from 'termui/components';

<StreamingText text="Hello, world!" animate speed={40} />;

Usage — live AI token stream:

import { StreamingText } from 'termui/components';

async function* tokenStream() {
  for (const chunk of ['Hello', ', ', 'world', '!']) {
    await new Promise((r) => setTimeout(r, 80));
    yield chunk;
  }
}

<StreamingText stream={tokenStream()} onComplete={(t) => console.log('done:', t)} />;