RGBA Color API

Color representation and utilities for terminal rendering

RGBA Class

The RGBA class represents colors as normalized RGBA values (0.0 to 1.0). It uses a Float32Array internally for efficient FFI interop with the native rendering layer.

Constructor

new RGBA · constructor

Create an RGBA color from a Float32Array buffer

constructor(buffer: Float32Array)

buffer · Float32Array · required

4-element array containing [r, g, b, a] values (0.0 to 1.0)

In most cases, use the static factory methods instead of calling the constructor directly.

Factory Methods

RGBA.fromValues · function

Create from normalized RGBA values

static fromValues(r: number, g: number, b: number, a?: number): RGBA

r · number · required

Red component (0.0 to 1.0)

g · number · required

Green component (0.0 to 1.0)

b · number · required

Blue component (0.0 to 1.0)

a · number

Alpha component (0.0 to 1.0). Default: 1.0

RGBA.fromInts · function

Create from integer RGBA values (0-255)

static fromInts(r: number, g: number, b: number, a?: number): RGBA

r · number · required

Red component (0 to 255)

g · number · required

Green component (0 to 255)

b · number · required

Blue component (0 to 255)

a · number

Alpha component (0 to 255). Default: 255

RGBA.fromHex · function

Create from a hex color string

static fromHex(hex: string): RGBA

hex · string · required

Hex color: "#RGB", "#RRGGBB", "#RGBA", or "#RRGGBBAA" (with or without #)

Returns magenta (#FF00FF) if the hex string is invalid.

RGBA.fromArray · function

Create from an existing Float32Array

static fromArray(array: Float32Array): RGBA

Properties

r · number

Red component (0.0 to 1.0)

g · number

Green component (0.0 to 1.0)

b · number

Blue component (0.0 to 1.0)

a · number

Alpha component (0.0 to 1.0)

buffer · Float32Array

Underlying storage buffer

Methods

toInts · function

Convert to integer RGBA values

toInts(): [number, number, number, number]

Returns an array of integers (0-255).

toString · function

Convert to string representation

toString(): string

Returns a string like "rgba(0.50, 0.75, 1.00, 1.00)".

equals · function

Check equality with another color

equals(other?: RGBA): boolean

Returns true if all components are equal.

map · function

Map a function over all components

map<R>(fn: (value: number) => R): [R, R, R, R]

Example:

const color = RGBA.fromValues(0.5, 0.5, 0.5, 1.0)
const doubled = color.map(x => x * 2)  // [1.0, 1.0, 1.0, 2.0]

Color Utilities

Hex Conversion

hexToRgb · function

Convert hex string to RGBA

function hexToRgb(hex: string): RGBA

Supports 3, 4, 6, and 8 character hex codes (with or without #).

rgbToHex · function

Convert RGBA to hex string

function rgbToHex(rgb: RGBA): string

Returns 6-character hex for opaque colors, 8-character for transparent.

Color Space Conversion

hsvToRgb · function

Convert HSV to RGB

function hsvToRgb(h: number, s: number, v: number): RGBA

h · number · required

Hue (0 to 360)

s · number · required

Saturation (0.0 to 1.0)

v · number · required

Value/Brightness (0.0 to 1.0)

Always returns opaque color (alpha = 1.0).

Color Parsing

parseColor · function

Parse a color from string or RGBA object

function parseColor(color: ColorInput): RGBA

color · string | RGBA · required

Color to parse

Supports:

• Hex colors: "#FF0000", "#F00", etc.
• CSS color names: "red", "blue", "transparent", etc.
• Existing RGBA objects (returned as-is)

CSS Color Names

Supported color names:

• Basic: black, white, red, green, blue, yellow, cyan, magenta
• Extended: gray/grey, silver, maroon, olive, lime, aqua, teal, navy, fuchsia, purple, orange
• Bright: brightblack, brightred, brightgreen, brightblue, brightyellow, brightcyan, brightmagenta, brightwhite
• Special: transparent (returns rgba(0, 0, 0, 0))

Examples

Creating Colors

import { RGBA } from "@opentui/core"

// From normalized values (0.0 to 1.0)
const red = RGBA.fromValues(1.0, 0.0, 0.0, 1.0)

// From integers (0 to 255)
const green = RGBA.fromInts(0, 255, 0)

// From hex
const blue = RGBA.fromHex("#0000FF")
const blueShort = RGBA.fromHex("#00F")
const semiTransparent = RGBA.fromHex("#FF000080")

// Transparent
const transparent = RGBA.fromValues(0, 0, 0, 0)

Using parseColor

import { parseColor } from "@opentui/core"

const color1 = parseColor("red")           // CSS name
const color2 = parseColor("#FF0000")       // Hex
const color3 = parseColor("transparent")   // Special
const color4 = parseColor(RGBA.fromInts(255, 0, 0))  // Pass-through

Color Manipulation

const color = RGBA.fromHex("#FF8800")

// Access components
console.log(color.r, color.g, color.b, color.a)

// Modify components
color.a = 0.5  // Make semi-transparent

// Convert to integers
const [r, g, b, a] = color.toInts()  // [255, 136, 0, 128]

// Convert to hex
import { rgbToHex } from "@opentui/core"
const hex = rgbToHex(color)  // "#ff880080"

// Compare colors
const other = RGBA.fromHex("#FF8800")
console.log(color.equals(other))  // false (different alpha)

HSV Color Generation

import { hsvToRgb } from "@opentui/core"

// Create a rainbow
for (let i = 0; i < 360; i += 30) {
  const color = hsvToRgb(i, 1.0, 1.0)
  console.log(`Hue ${i}:`, color.toString())
}

Using with FrameBuffer

import { OptimizedBuffer, RGBA } from "@opentui/core"

const buffer = OptimizedBuffer.create(80, 24, "unicode")

// Use colors in rendering
const fg = RGBA.fromHex("#00FF00")
const bg = RGBA.fromValues(0.1, 0.1, 0.1, 1.0)

buffer.drawText("Hello", 0, 0, fg, bg)

// Semi-transparent overlay
const overlay = RGBA.fromValues(1, 0, 0, 0.3)
buffer.fillRect(10, 5, 20, 10, overlay)

Type Definitions

type ColorInput = string | RGBA

interface RGBA {
  r: number
  g: number
  b: number
  a: number
  buffer: Float32Array
  
  toInts(): [number, number, number, number]
  toString(): string
  equals(other?: RGBA): boolean
  map<R>(fn: (value: number) => R): [R, R, R, R]
}