Skip to content

Color API ​

parseHexColor Parse ​

Parses rgb, rgba, rrggbb, or rrggbbaa, with or without #.

Signature ​

ts
export function parseHexColor(value: string): RgbaColor;

Example ​

ts
import { parseHexColor } from "@fast-china/utils";

const result = parseHexColor("#409eff");

Input ​

InputTypeRequired / defaultDescription
valuestringRequiredHexadecimal color text.

Returns ​

ValueTypeDescription
resultRgbaColorNormalized RGBA object; alpha defaults to 1.

formatHexColor Format ​

Formats an RGB or RGBA object as a lowercase hexadecimal color.

Signature ​

ts
export function formatHexColor(color: RgbColor | RgbaColor, includeAlpha: boolean = "alpha" in color && color.alpha < 1): string;

Example ​

ts
import { formatHexColor } from "@fast-china/utils";

const result = formatHexColor({ red: 64, green: 158, blue: 255 });

Input ​

InputTypeRequired / defaultDescription
colorRgbColor | RgbaColorRequiredColor channels; RGB values are rounded to the nearest integer.
includeAlphabooleanOptional; defaults to "alpha" in color && color.alpha < 1Whether to include alpha; by default included only when supplied and less than 1.

Returns ​

ValueTypeDescription
resultstringLowercase #rrggbb or #rrggbbaa text.

mixHexColors Blend ​

Linearly blends two hexadecimal colors, including alpha.

Signature ​

ts
export function mixHexColors(first: string, second: string, amount: number): string;

Example ​

ts
import { mixHexColors } from "@fast-china/utils";

const result = mixHexColors("#000000", "#ffffff", 0.5);

Input ​

InputTypeRequired / defaultDescription
firststringRequiredColor at amount = 0.
secondstringRequiredColor at amount = 1.
amountnumberRequiredBlend ratio from 0 to 1.

Returns ​

ValueTypeDescription
resultstringLowercase hexadecimal color; retains alpha if either input includes it.

mixHexColorWithBlack Blend ​

Blends toward black by a ratio.

Signature ​

ts
export function mixHexColorWithBlack(color: string, amount: number): string;

Example ​

ts
import { mixHexColorWithBlack } from "@fast-china/utils";

const result = mixHexColorWithBlack("#409eff", 0.5);

Input ​

InputTypeRequired / defaultDescription
colorstringRequiredValid hexadecimal color.
amountnumberRequiredBlend ratio from 0 to 1.

Returns ​

ValueTypeDescription
resultstringHexadecimal color blended with black; shares the blend function's argument and exception semantics.

mixHexColorWithWhite Blend ​

Blends toward white by a ratio.

Signature ​

ts
export function mixHexColorWithWhite(color: string, amount: number): string;

Example ​

ts
import { mixHexColorWithWhite } from "@fast-china/utils";

const result = mixHexColorWithWhite("#409eff", 0.5);

Input ​

InputTypeRequired / defaultDescription
colorstringRequiredValid hexadecimal color.
amountnumberRequiredBlend ratio from 0 to 1.

Returns ​

ValueTypeDescription
resultstringHexadecimal color blended with white; shares the blend function's argument and exception semantics.

relativeLuminance Luminance ​

Calculates WCAG sRGB relative luminance.

Signature ​

ts
export function relativeLuminance(color: string): number;

Example ​

ts
import { relativeLuminance } from "@fast-china/utils";

const result = relativeLuminance("#409eff");

Input ​

InputTypeRequired / defaultDescription
colorstringRequiredValid hexadecimal color.

Returns ​

ValueTypeDescription
resultnumberRelative luminance from 0 to 1.

contrastRatio Contrast ​

Calculates the WCAG contrast ratio of two opaque colors, from 1 to 21.

Signature ​

ts
export function contrastRatio(first: string, second: string): number;

Example ​

ts
import { contrastRatio } from "@fast-china/utils";

const result = contrastRatio("#000000", "#ffffff");

Input ​

InputTypeRequired / defaultDescription
firststringRequiredFirst hexadecimal color.
secondstringRequiredSecond hexadecimal color.

Returns ​

ValueTypeDescription
resultnumberContrast ratio of the lighter and darker colors.

pickHigherContrastColor Contrast ​

Chooses the candidate with higher contrast against the background.

Signature ​

ts
export function pickHigherContrastColor(background: string, first = "#000000", second = "#ffffff"): string;

Example ​

ts
import { pickHigherContrastColor } from "@fast-china/utils";

const result = pickHigherContrastColor("#ffffff", "#000000", "#ffffff");

Input ​

InputTypeRequired / defaultDescription
backgroundstringRequiredActual opaque background color.
firstunknownOptional; defaults to "#000000"First candidate; black by default.
secondunknownOptional; defaults to "#ffffff"Second candidate; white by default.

Returns ​

ValueTypeDescription
resultstringOriginal candidate string with higher contrast; returns first on a tie.