Colors

Most color options accept ColorInput, which is string | RGBA. Use a string for ordinary component styling and RGBA for computed values.

import { BoxRenderable, TextRenderable, createCliRenderer, parseColor } from "@opentui/core"

const accent = parseColor("#22c55e")
const renderer = await createCliRenderer()

const content = new BoxRenderable(renderer, {
  backgroundColor: "#101418",
  borderColor: "gray",
  border: true,
})
content.add(new TextRenderable(renderer, { content: "Ready", fg: accent }))
renderer.root.add(content)

Parse everyday colors#

parseColor() accepts an RGBA unchanged. String matching is case-insensitive.

Hex strings can use #RGB, #RGBA, #RRGGBB, or #RRGGBBAA. Alpha is last and defaults to 255.

"transparent" produces [0, 0, 0, 0].

The named-color set is limited to these values:

• black, white, red, green, blue, yellow, cyan, and magenta
• silver, gray, grey, maroon, olive, lime, aqua, teal, navy, fuchsia, purple, and orange
• brightBlack, brightRed, brightGreen, brightBlue, brightYellow, brightCyan, brightMagenta, and brightWhite

An invalid string logs a warning and returns opaque magenta. parseColor() does not support arbitrary CSS color syntax.

Create RGBA values#

RGBA stores four 8-bit channels. The class exposes normalized channel getters from 0 to 1.

import { RGBA } from "@opentui/core"

const fromBytes = RGBA.fromInts(34, 197, 94)
const fromFloats = RGBA.fromValues(0.13, 0.77, 0.37, 0.5)
const fromHex = RGBA.fromHex("#22c55e80")

fromInts() defaults alpha to 255. It clamps each channel to 0..255 and rounds to the nearest integer.

fromValues() defaults alpha to 1. It clamps each channel to 0..1, multiplies by 255, and rounds.

Both constructors convert a non-finite channel to 0. Channel setters apply the same normalized float conversion as fromValues().

RGBA.clone() copies all channels and metadata. equals() compares the complete packed value, including color intent.

Use alpha#

An alpha value of zero is transparent. Intermediate alpha values blend during supported buffer-composition operations.

After a blend, the result is a literal RGB color. It no longer identifies a terminal default or indexed palette slot.

See FrameBuffer and the Buffer API for direct alpha drawing.

Preserve terminal palette intent#

Every RGBA also carries one color intent:

import { RGBA } from "@opentui/core"

const warning = RGBA.fromIndex(3)
const foreground = RGBA.defaultForeground()
const background = RGBA.defaultBackground("#101418")

console.log(warning.intent, warning.slot)
console.log(foreground.intent, background.intent)

fromIndex() requires an integer from 0 through 255 and throws RangeError otherwise. Its default RGB snapshot comes from the built-in ANSI 256-color table.

Default foreground uses [255, 255, 255] as its snapshot. Default background uses [0, 0, 0].

An optional snapshot supplies RGBA data for blending and early frames. It does not change the indexed or default intent.

Detected palette changes can alter terminal output for indexed and default intent. Read Terminal capabilities for detection timing.

Understand packed transport#

RGBA.buffer is a Uint16Array(4). The low byte of each element stores one RGBA channel.

The four high bytes store 32 bits of metadata. Indexed intent includes its palette slot in that metadata.

This packed form crosses the native boundary and participates in exact frame comparisons. Two colors with equal RGBA channels can still differ by intent.

Use this representation only for low-level transport. Everyday component code should use ColorInput, parseColor(), and the constructors.

See Text and terminal cells for the attributes and cell data that travel with colors.

Next#

See Text, Box, and FrameBuffer for color options. See FrameBuffer color matrices for post-processing.