gradient

The gradient() function applies a smooth multi-stop color gradient across a string, coloring each character individually. All three color levels — named 4-bit strings, 8-bit palette codes, and 24-bit RGB values — are accepted as stops. Under the hood every stop is converted to RGB and linearly interpolated per character, so you get pixel-perfect blending regardless of which color type you mix.

This is the lower-level building block behind the smooth mode of rainbow(), and it gives you full control over which colors to blend and over what span.

Signature

function gradient(
text: string,
colors: AnyColor[],
isBackground?: boolean,
size?: number,
): string

Parameters

• text — the string to colorize. Unicode code points are handled correctly (a multi-byte emoji counts as one character).
• colors — two or more color stops. The first stop is applied at the start of the string and the last at the end; any stops in between divide the string into equal segments. Accepts any AnyColor: named strings like "cyan", eightBit() values, or rgb() / hex() values — or any mix of the three.
• isBackground — when true, the gradient is applied to the character background instead of the foreground. Defaults to false.
• size — the virtual width used for the interpolation position calculation. Defaults to text.length. Setting this to a fixed number lets you render the same gradient across strings of different lengths (for example, two lines of a multi-line banner).

Return Value

A new string where each character is wrapped in the appropriate ANSI foreground (or background) escape sequence. The return value ends with a default-color reset so text printed after it is unaffected.

Usage

import { gradient, rgb } from "ts-better-console";

// Fade from cyan to magenta
console.log(
gradient("Hello, gradient!", ["cyan", "magenta"])
);

Notes

• Passes an empty string through unchanged.
• A single color stop behaves like a plain s() call — the whole string is painted that one color.
• All color types are normalized to RGB internally for interpolation, so mixing named strings, eightBit(), and rgb() / hex() in the same stop list works fine.
• The output is a regular string with embedded ANSI codes — it can be passed to console.log, concatenated, or used inside a cs() call.

Import

import { gradient } from "ts-better-console";