Text

Text displays styled text with colors, attributes, and selection. Use it for labels and prose. Use Code or Markdown for parsed rich content.

Availability#

Field	Availability
Package	`@aicippytui/core`
Core renderable	`TextRenderable`
React	`<text>` (automatic)
Solid	`<text>` (automatic)
Status	Built in

Basic usage#

Renderable API#

import { TextRenderable, createCliRenderer } from "@aicippytui/core"

const renderer = await createCliRenderer()

const text = new TextRenderable(renderer, {
  id: "greeting",
  content: "Hello, AiCIPPYTUI!",
  fg: "#00FF00",
})

renderer.root.add(text)

Text attributes#

Combine multiple text attributes using bitwise OR:

import { TextRenderable, TextAttributes } from "@aicippytui/core"

const styledText = new TextRenderable(renderer, {
  id: "styled",
  content: "Important Message",
  fg: "#FFFF00",
  attributes: TextAttributes.BOLD | TextAttributes.UNDERLINE,
})

Bold, italic, and underline can also be applied independently:

bold       Important message  italic     Additional context underline  Documentation

Available attributes#

Attribute	Description
`TextAttributes.BOLD`	Bold text
`TextAttributes.DIM`	Dimmed text
`TextAttributes.ITALIC`	Italic text
`TextAttributes.UNDERLINE`	Underlined text
`TextAttributes.BLINK`	Blinking text
`TextAttributes.INVERSE`	Inverted colors
`TextAttributes.HIDDEN`	Hidden text
`TextAttributes.STRIKETHROUGH`	Strikethrough text

Template literals for rich text#

Use the t template literal for inline styling within a single text element:

import { TextRenderable, t, bold, underline, fg, bg, italic } from "@aicippytui/core"

const richText = new TextRenderable(renderer, {
  id: "rich",
  content: t`${bold("Important:")} ${fg("#FF0000")(underline("Warning!"))} Normal text`,
})

Available style functions#

import { t, bold, dim, italic, underline, blink, reverse, strikethrough, fg, bg } from "@aicippytui/core"

// Basic attributes
t`${bold("bold text")}`
t`${italic("italic text")}`
t`${underline("underlined")}`
t`${strikethrough("deleted")}`

// Colors
t`${fg("#FF0000")("red text")}`
t`${bg("#0000FF")("blue background")}`

// Combining styles
t`${bold(fg("#FFFF00")("bold yellow"))}`

React and Solid can compose inline , , , , , ,  , and <a href> elements inside <text>. They are text-only children and cannot mount under a Box or another layout element directly. See inline text elements for availability.

Positioning#

const text = new TextRenderable(renderer, {
  id: "positioned",
  content: "Absolute position",
  position: "absolute",
  left: 10,
  top: 5,
})

Align lines#

textAlign pads each rendered line inside the text width. The pad for one line does not depend on the longest line.

const text = new TextRenderable(renderer, {
  content: "hi\nworld",
  width: 10,
  height: 2,
  textAlign: "center",
})

left        center      right     0123456789  0123456789  0123456789hi              hi              hiworld         world          world

"left" is the default. "center" and "right" use leftover columns in the text width. A line that already fills the text width does not move.

Set a width, or let a parent stretch the text. Alignment has no effect when every line already fills the text width.

Wrapping runs first. Then textAlign pads each rendered line.

Change textAlign after mount with text.textAlign = "right". CodeRenderable inherits the same option.

textAlign does not replace Yoga box alignment.

Text selection#

Enable text selection for copying:

const selectableText = new TextRenderable(renderer, {
  id: "selectable",
  content: "Select me!",
  selectable: true, // Default is true
})

const nonSelectable = new TextRenderable(renderer, {
  id: "label",
  content: "Button Label",
  selectable: false, // Disable selection
})

Properties#

Property	Type	Default	Description
`content`	`string \| StyledText`	`""`	The text content to display
`fg`	`string \| RGBA`	`#FFFFFF`	Foreground (text) color
`bg`	`string \| RGBA`	transparent	Background color
`attributes`	`TextAttributes`	`0`	Text styling attributes
`selectable`	`boolean`	`true`	Whether text can be selected
`wrapMode`	`"none" \| "char" \| "word"`	`"word"`	Line wrapping mode
`textAlign`	`"left" \| "center" \| "right"`	`"left"`	Per-line alignment within the text width
`position`	`"relative" \| "absolute"`	`"relative"`	Positioning mode
`left`, `top`, `right`, `bottom`	`number \| "auto" \| "{number}%"`	-	Position offsets

Example: status bar#

import { TextRenderable, BoxRenderable, t, bold, fg } from "@aicippytui/core"

const statusBar = new BoxRenderable(renderer, {
  position: "absolute",
  bottom: 0,
  width: "100%",
  height: 1,
  backgroundColor: "#333333",
  flexDirection: "row",
  justifyContent: "space-between",
  paddingLeft: 1,
  paddingRight: 1,
})
statusBar.add(
  new TextRenderable(renderer, {
    content: t`${bold("myfile.ts")} - ${fg("#888888")("TypeScript")}`,
  }),
)
statusBar.add(
  new TextRenderable(renderer, {
    content: t`Ln ${fg("#00FF00")("42")}, Col ${fg("#00FF00")("15")}`,
  }),
)

renderer.root.add(statusBar)

Read Text and terminal cells for graphemes, wrapping, alignment, and display-cell widths. See Colors, Layout, and Interaction, focus, and selection for shared behavior. Use Box to lay out text with other components.