Color

The core immutable color class. Stores RGBA internally with derived HSL access. All mutation methods return a new instance.

import type { Color } from "@driangle/kleur";

Color is exported as a type only — use kleur() or the creation functions (kleur.hex(), kleur.rgb(), kleur.hsl(), etc.) to create instances. See Parsing & Creation for the full list.

Channel Getters

Interactive Demo

Channel getters

Pick a color to see all channel getter values update live.

kleur("#ff7f50")

Color

#ff7f50

Getter	Value	Range
red	255	0-255
green	127	0-255
blue	80	0-255
hue	16.114285714285714	0-360
saturationHsl	100	0-100
lightness	65.68627450980392	0-100
saturationHsb	68.62745098039215	0-100
brightness	100	0-100
alpha	1	0-1
hsl	{ "h": 16.114285714285714, "s": 100, "l": 65.68627450980392 }
hsb	{ "h": 16.11428571428572, "s": 68.62745098039215, "b": 100 }

Immutable Setters

Each returns a new Color with the specified channel replaced:

Method	Param	Description
withRed(v)	number (0-255)	Set red channel
withGreen(v)	number (0-255)	Set green channel
withBlue(v)	number (0-255)	Set blue channel
withAlpha(v)	number (0-1)	Set alpha
withHue(v)	number (0-360)	Set hue
withSaturationHsl(v)	number (0-100)	Set HSL saturation
withSaturationHsb(v)	number (0-100)	Set HSB saturation
withLightness(v)	number (0-100)	Set lightness
withBrightness(v)	number (0-100)	Set HSB brightness

const red = kleur("#ff0000");
const blue = red.withHue(240); // same saturation/lightness, different hue

Systematic Channel Operations

Interactive Demo

Systematic channel operations

Explore the three operation modes — absolute, additive, and multiplicative — across every channel.

kleur("#ff6600").withLightness(70)

Base Color

ChannelLightnessBrightnessHSL SaturationHSB SaturationHueAlphaModeAbsolute (withX)Additive (adjustX)Multiplicative (scaleX)Value: 70

Original#ff6600

Result#ffa366

For channels that support multiple kinds of adjustment, the API follows a consistent pattern:

• withX(value) sets an absolute value
• adjustX(delta) adds a delta in channel units
• scaleX(factor) multiplies the current value

Channel	Absolute	Additive	Multiplicative
Alpha	withAlpha(v)	adjustAlpha(delta)	scaleAlpha(factor)
Hue	withHue(v)	adjustHue(delta)	—
HSL saturation	withSaturationHsl(v)	adjustSaturationHsl(delta)	scaleSaturationHsl(factor)
HSB saturation	withSaturationHsb(v)	adjustSaturationHsb(delta)	scaleSaturationHsb(factor)
Lightness	withLightness(v)	adjustLightness(delta)	scaleLightness(factor)
Brightness	withBrightness(v)	adjustBrightness(delta)	scaleBrightness(factor)

const color = kleur("#ff6600");

color.withLightness(70);
color.adjustLightness(10);
color.scaleLightness(1.2);

Output Formats

Method	Returns	Example
toHex()	string	"#ff7f50" (6-digit, no alpha)
toHex8()	string	"#ff7f50ff" (8-digit, includes alpha)
toCss()	string	"rgba(255,127,80,1)"
toRgb()	Rgb	{ r: 255, g: 127, b: 80 }
toRgba()	Rgba	{ r: 255, g: 127, b: 80, a: 1 }
toHsl()	Hsl	{ h: 16, s: 100, l: 66 }
toHsla()	Hsla	{ h: 16, s: 100, l: 66, a: 1 }
toArray()	[r, g, b, a]	[255, 127, 80, 1]
toNormalized()	[r, g, b, a]	[1, 0.498, 0.314, 1] (0-1 range)
toString()	string	Same as toCss()

Color Adjustments

All adjustment methods return a new Color.

Interactive Demo

Explore immutable adjustments

Change one color operation at a time and compare the original with the returned new color.

kleur("#ff7f50").lighten(0.3)

Base Color

Operationlighten()darken()saturate()desaturate()rotate()warm()cool()invert()grayscale()complement()Amount: 0.3

Original#ff7f50

Result#ffa585

Lightness & Brightness

Method	Param	Description
adjustLightness(delta)	number	Add to HSL lightness in channel units.
lighten(amount)	number (0-1)	Lighten by proportion of remaining headroom. 0.3 = 30% toward white.
darken(amount)	number (0-1)	Darken by proportion of current lightness. 0.3 = 30% toward black.
scaleLightness(factor)	number	Multiply lightness by factor. 1.5 = 50% brighter.
adjustBrightness(delta)	number	Add to HSB brightness in channel units.
scaleBrightness(factor)	number	Multiply brightness by factor.

Saturation

Method	Param	Description
adjustSaturationHsl(delta)	number	Add to HSL saturation in channel units.
saturate(amount)	number (0-1)	Saturate by proportion of remaining headroom toward 100.
saturateHsl(amount)	number (0-1)	Alias for saturate().
desaturate(amount)	number (0-1)	Desaturate by proportion of current saturation toward 0.
desaturateHsl(amount)	number (0-1)	Alias for desaturate().
scaleSaturationHsl(factor)	number	Multiply HSL saturation by factor.
adjustSaturationHsb(delta)	number	Add to HSB saturation in channel units.
scaleSaturationHsb(factor)	number	Multiply HSB saturation by factor.
grayscale()	—	Remove all HSL saturation (equivalent to desaturate(1)).

Hue

Method	Param	Description
adjustHue(delta)	number	Add to hue and wrap around 360.
rotate(degrees)	number	Rotate hue on the color wheel.
complement()	—	Rotate hue by 180 degrees.
warm(intensity?)	number 0–1 (default 0.2)	Shift hue toward 30° (warm). Intensity is an interpolation factor.
cool(intensity?)	number 0–1 (default 0.2)	Shift hue toward 240° (cool). Intensity is an interpolation factor.

Alpha & Inversion

Method	Param	Description
adjustAlpha(delta)	number	Add to alpha, clamped to 0-1.
scaleAlpha(factor)	number	Multiply alpha by factor, clamped to 0-1.
opaque()	—	Set alpha to 1.
invert()	—	Invert RGB channels (255 - value).

Interpolation & Blending

Interactive Demo

Blend or mix two colors

Compare midpoint interpolation with common blend modes using the same pair of colors.

kleur.mix(
  kleur("#ff0000"),
  kleur("#0000ff"),
  0.5
)

Base

Overlay

Modemix()blend(..., "screen")blend(..., "multiply")blend(..., "overlay")blend(..., "difference")blend(..., "lighten")blend(..., "darken")Mix Amount: 0.5

Base

Overlay

Result

#800080

mix(target: Color, t?: number, ease?: (t: number) => number): Color

Linear interpolation in RGB space between this and target. t=0 returns this, t=1 returns target. The optional ease function remaps t before interpolation.

const a = kleur("#ff0000");
const b = kleur("#0000ff");

a.mix(b, 0.5).toHex(); // midpoint between red and blue
a.mix(b, 0.25).toHex(); // 25% toward blue

blend(overlay: KleurValue, mode: BlendMode): Color

Blend this color with overlay using the specified blend mode. Instance shorthand for kleur.blend(this, overlay, mode).

const base = kleur("#ff6600");

base.blend("#0066ff", "multiply").toHex();
base.blend("#0066ff", "screen").toHex();
base.blend("#ffffff", (b, o) => kleur.rgb(b.red, o.green, b.blue));

Harmony

These methods are convenience shortcuts for the harmony functions available on the kleur namespace. They return the same results but can be called directly on a Color instance.

Method	Returns	Description
triadic()	Palette	3 colors, 120 degrees apart
tetradic()	Palette	4 colors, 90 degrees apart
analogous(angle?)	Palette	3 adjacent colors (default 30°)
splitComplement(angle?)	Palette	Base + two near the complement (default 30°)
tints(count)	Palette	Progressively lighter variations
shades(count)	Palette	Progressively darker variations
tones(count)	Palette	Progressively desaturated variations

const coral = kleur("#ff6347");

const [base, second, third] = coral.triadic();
const lighter = coral.tints(5);
const darker = coral.shades(3);

Interactive Demo

Explore color harmonies

See how harmony functions distribute colors around the hue wheel.

kleur("#e64a19").triadic()

Base Color

Harmonytriadic()tetradic()analogous()splitComplement()

#e64a19

#19e64a

#4a19e6