Overview
The RGBirdflop SDK provides a unified gradient interface that supports multiple color space interpolation methods. The ColorGradient and ColorAnimatedGradient classes offer perceptually smooth color transitions using various color spaces.
ColorGradient
Unified gradient interface that can switch between RGB, HSL, OKLAB, OKLCh, CIELAB, and LuvLCh interpolation.
Constructor
class ColorGradient {
constructor(
colors: { rgb: number[], pos: number }[],
numSteps: number,
type?: GradientType
)
}
colors
Array<{ rgb: number[], pos: number }>
required
Array of color stops with RGB values and positions.
rgb: RGB array [r, g, b] with values in 0-255 rangepos: Position in gradient (0-100)
Number of steps in the gradient sequence
type
GradientType
default:"'rgb'"
Interpolation type: ‘rgb’, ‘hsl’, ‘oklab’, ‘oklch’, ‘cielab’, or ‘luvLch’
Methods
next()
Gets the next color in the gradient sequence.
RGB array [r, g, b] with values in 0-255 range
getType()
Gets the current gradient type.
The interpolation type used by this gradient
Usage Example
import { ColorGradient, hexToRGB } from '@birdflop/rgbirdflop';
const colors = [
{ rgb: hexToRGB('#FF0000'), pos: 0 },
{ rgb: hexToRGB('#0000FF'), pos: 100 }
];
const gradient = new ColorGradient(colors, 10, 'oklab');
for (let i = 0; i < 10; i++) {
const color = gradient.next();
console.log(`Step ${i}: RGB(${color.join(', ')})`);
}
ColorAnimatedGradient
Animated gradient interface with offset support for creating animation effects.
Constructor
class ColorAnimatedGradient {
constructor(
colors: { rgb: number[], pos: number }[],
numSteps: number,
offset: number,
type?: GradientType
)
}
colors
Array<{ rgb: number[], pos: number }>
required
Array of color stops with RGB values and positions
Number of steps in the gradient sequence
Starting offset for animation (used to shift the gradient)
type
GradientType
default:"'rgb'"
Interpolation type
Methods
Same as ColorGradient: next() and getType()
Usage Example
import { ColorAnimatedGradient, hexToRGB } from '@birdflop/rgbirdflop';
const colors = [
{ rgb: hexToRGB('#54daf4'), pos: 0 },
{ rgb: hexToRGB('#545eb6'), pos: 100 }
];
// Create animation frames
for (let frame = 0; frame < 20; frame++) {
const gradient = new ColorAnimatedGradient(colors, 8, frame, 'hsl');
const frameColors = [];
for (let i = 0; i < 8; i++) {
frameColors.push(gradient.next());
}
console.log(`Frame ${frame}:`, frameColors);
}
GradientType
Union type of all available gradient interpolation types.
type GradientType = 'rgb' | 'hsl' | 'oklab' | 'oklch' | 'cielab' | 'luvLch'
Available Types
Linear RGB interpolation - Fast, simple, but may appear muddy in some transitions (e.g., red to green passes through brown)
HSL color space interpolation - Intuitive color transitions that follow the color wheel, great for rainbow effects
OKLAB interpolation - Perceptually uniform color space, recommended for smooth, natural-looking gradients
OKLCh interpolation - Cylindrical OKLAB (Lightness, Chroma, Hue), great for controlling saturation and brightness
CIE Lab interpolation* - Industry-standard perceptually uniform color space
CIE LCh (based on CIELUV) - Alternative perceptually uniform cylindrical color space
Comparison Example
import { ColorGradient, hexToRGB, rgbToHex } from '@birdflop/rgbirdflop';
const colors = [
{ rgb: hexToRGB('#FF0000'), pos: 0 },
{ rgb: hexToRGB('#00FF00'), pos: 100 }
];
const types: GradientType[] = ['rgb', 'hsl', 'oklab', 'oklch'];
types.forEach(type => {
const gradient = new ColorGradient(colors, 5, type);
console.log(`${type}:`);
for (let i = 0; i < 5; i++) {
const color = gradient.next();
console.log(` Step ${i}: #${rgbToHex(color)}`);
}
});
// Output shows different midpoint colors:
// rgb: passes through brown/yellow tones
// hsl: vivid yellow midpoint
// oklab: perceptually smooth transition
// oklch: controlled chroma transition
GRADIENT_TYPES
Const array containing all available gradient type values (single source of truth).
const GRADIENT_TYPES = ['rgb', 'hsl', 'oklab', 'oklch', 'cielab', 'luvLch'] as const
Individual Gradient Classes
For direct use, you can import specific gradient implementations:
import {
RgbGradient,
RgbAnimatedGradient,
HslGradient,
HslAnimatedGradient,
OklabGradient,
OklabAnimatedGradient,
OklchGradient,
OklchAnimatedGradient,
CielabGradient,
CielabAnimatedGradient,
LuvLChGradient,
LuvLChAnimatedGradient
} from '@birdflop/rgbirdflop';
ColorGradient and ColorAnimatedGradient.
Base Gradient Architecture
TwoStopGradient Interface
Each gradient type implements this interface for two-color interpolation:
interface TwoStopGradient {
lowerRange: number;
upperRange: number;
colorAt(step: number): number[];
}
BaseGradient Class
Common gradient logic shared by all gradient types:
- Normalizes color stops (ensures 0% and 100% positions)
- Creates gradient segments between color pairs
- Handles step sequencing with easing function
- Manages color stop position swapping
Advanced Usage
Custom Color Positions
const colors = [
{ rgb: hexToRGB('#FF0000'), pos: 0 },
{ rgb: hexToRGB('#FFFF00'), pos: 20 },
{ rgb: hexToRGB('#00FF00'), pos: 80 },
{ rgb: hexToRGB('#0000FF'), pos: 100 }
];
const gradient = new ColorGradient(colors, 100, 'oklch');
// Quick transition from red to yellow,
// then slow transition to green,
// then quick to blue
Multi-Color Text Gradient
import { ColorGradient, hexToRGB, rgbToHex } from '@birdflop/rgbirdflop';
const text = 'Rainbow';
const colors = [
{ rgb: hexToRGB('#FF0000'), pos: 0 },
{ rgb: hexToRGB('#FF7F00'), pos: 16.67 },
{ rgb: hexToRGB('#FFFF00'), pos: 33.33 },
{ rgb: hexToRGB('#00FF00'), pos: 50 },
{ rgb: hexToRGB('#0000FF'), pos: 66.67 },
{ rgb: hexToRGB('#4B0082'), pos: 83.33 },
{ rgb: hexToRGB('#9400D3'), pos: 100 }
];
const gradient = new ColorGradient(colors, text.length, 'hsl');
const result = Array.from(text).map((char, i) => {
const color = gradient.next();
return `<color:#${rgbToHex(color)}>${char}</color>`;
}).join('');
console.log(result);
Implementation
Source: packages/rgbirdflop/src/util/ColorUtils/index.ts:24
Base implementation: packages/rgbirdflop/src/util/ColorUtils/BaseGradient.ts:81