claude-code/packages/@ant/ink/docs/03-text-and-styling.md

Chapter 3: Text & Styling

Text Component

Text renders styled text content. It supports colors, emphasis, and text wrapping.

import { Text } from '@anthropic/ink'

<Text bold color="success">Operation complete</Text>

Text Props

Prop	Type	Default	Description
color	keyof Theme | Color	-	Foreground color
backgroundColor	keyof Theme	-	Background color (theme-aware)
bold	boolean	false	Bold text
dimColor	boolean	false	Dim text (uses theme's inactive color)
italic	boolean	false	Italic text
underline	boolean	false	Underlined text
strikethrough	boolean	false	Strikethrough text
inverse	boolean	false	Swap foreground/background
wrap	TextWrap	'wrap'	Wrapping/truncation mode
children	ReactNode	-	Text content

Note: bold and dimColor are mutually exclusive (ANSI terminals cannot render both simultaneously).

BaseText vs ThemedText

• BaseText -- Accepts raw Color values only
• Text (default export) -- Theme-aware, accepts keyof Theme | Color for color, and keyof Theme for backgroundColor

// Raw color
<BaseText color="rgb(255,0,0)">Red text</BaseText>

// Theme key (resolved to current theme palette)
<Text color="error">Error message</Text>

// Mixed
<Text color="#FF0000">Custom red</Text>

Text Wrap Modes

<Text wrap="wrap">...</Text>                // Word-wrap at container width (default)
<Text wrap="wrap-trim">...</Text>           // Wrap + trim trailing whitespace
<Text wrap="end">...</Text>                 // Truncate with "..." at end
<Text wrap="truncate-end">...</Text>        // Same as "end"
<Text wrap="truncate">...</Text>            // Truncate (no ellipsis)
<Text wrap="middle">...</Text>              // "start...end"
<Text wrap="truncate-middle">...</Text>     // Same as "middle"
<Text wrap="truncate-start">...</Text>      // "...text"

TextHoverColorContext

Uncolored Text children inherit a hover color from context:

import { TextHoverColorContext } from '@anthropic/ink'

<TextHoverColorContext.Provider value="suggestion">
  <Text>Uncolored text gets the suggestion color</Text>
  <Text color="error">This stays red</Text>
</TextHoverColorContext.Provider>

Precedence: explicit color > TextHoverColorContext > dimColor.

Color System

Raw Color Formats

Four formats are supported for raw color values:

// RGB
<Text color="rgb(255,107,128)">Bright red</Text>

// Hex
<Text color="#FF6B80">Bright red</Text>

// ANSI 256-color
<Text color="ansi256(196)">Red from 256-color palette</Text>

// Named ANSI 16-color
<Text color="ansi:red">Red</Text>
<Text color="ansi:greenBright">Bright green</Text>

ANSI Named Colors

Full list of ansi: prefixed names:

Name	Color
ansi:black	Black
ansi:red	Red
ansi:green	Green
ansi:yellow	Yellow
ansi:blue	Blue
ansi:magenta	Magenta
ansi:cyan	Cyan
ansi:white	White
ansi:blackBright	Dark gray
ansi:redBright	Bright red
ansi:greenBright	Bright green
ansi:yellowBright	Bright yellow
ansi:blueBright	Bright blue
ansi:magentaBright	Bright magenta
ansi:cyanBright	Bright cyan
ansi:whiteBright	Bright white

Utility Functions

color(colorValue, themeName, type?)

Curried theme-aware color function. Resolves theme keys to raw color values.

import { color } from '@anthropic/ink'

const paint = color('error', 'dark')  // Returns (text: string) => string
console.log(paint('failed'))          // 'failed' wrapped in ANSI red codes

const paintFg = color('rgb(255,0,0)', 'dark', 'foreground')
const paintBg = color('success', 'dark', 'background')

Parameters:

• c -- keyof Theme | Color | undefined -- Theme key or raw color
• theme -- ThemeName -- Current theme
• type -- 'foreground' | 'background' (default 'foreground')

stringWidth(text)

Measures the visual width of a string in terminal columns, accounting for:

• CJK characters (2 columns each)
• Emoji (2 columns each)
• ANSI escape sequences (0 columns)

import { stringWidth } from '@anthropic/ink'

stringWidth('hello')      // 5
stringWidth('你好')        // 4
stringWidth('\x1b[31mhi')  // 2 (ANSI codes ignored)

wrapText(text, width, textWrap)

Wraps text to a given width with the specified wrapping mode.

import { wrapText } from '@anthropic/ink'

wrapText('Hello World', 5, 'wrap')    // 'Hello\nWorld'
wrapText('Hello World', 8, 'end')     // 'Hello...'

wrapAnsi(text, width)

Wraps text containing ANSI escape codes while preserving styling.

import { wrapAnsi } from '@anthropic/ink'

wrapAnsi('\x1b[31mHello World\x1b[0m', 5)
// Wraps at word boundaries, keeps color codes intact

measureElement(node)

Measures a rendered DOM element's dimensions.

import { measureElement } from '@anthropic/ink'

const { width, height } = measureElement(domElement)

Link Component

Renders an OSC 8 terminal hyperlink (clickable URL in supported terminals).

import { Link } from '@anthropic/ink'

<Link url="https://example.com">
  <Text underline color="suggestion">example.com</Text>
</Link>

Props:

• url -- string (required) -- Target URL
• children -- ReactNode -- Display content
• fallback -- ReactNode -- Shown when hyperlinks are unsupported

RawAnsi Component

Renders pre-formatted ANSI strings directly into the layout.

import { RawAnsi } from '@anthropic/ink'

<RawAnsi
  lines={['\x1b[31mRed line 1\x1b[0m', '\x1b[32mGreen line 2\x1b[0m']}
  width={40}
/>

Props:

• lines -- string[] -- Pre-rendered ANSI lines (one terminal row each)
• width -- number -- Column width the producer wrapped to

Border Rendering

renderBorder(box, output, options?)

Low-level border rendering function used internally by Box.

import { renderBorder } from '@anthropic/ink'
import type { BorderTextOptions } from '@anthropic/ink'

Border styles available (from cli-boxes):

• single -- Thin lines ─│┌┐└┘
• double -- Double lines ═║╔╗╚╝
• round -- Rounded corners ─│╭╮╰╯
• bold -- Bold lines ━┃┏┓┗┛
• singleDouble -- Single horizontal, double vertical
• doubleSingle -- Double horizontal, single vertical
• classic -- ASCII ─|++++