Color API

parseHexColor Parse

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

Signature

export function parseHexColor(value: string): RgbaColor;

Example

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

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

Input

Input	Type	Required / default	Description
value	string	Required	Hexadecimal color text.

Returns

Value	Type	Description
result	RgbaColor	Normalized RGBA object; alpha defaults to 1.

formatHexColor Format

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

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
color	RgbColor | RgbaColor	Required	Color channels; RGB values are rounded to the nearest integer.
includeAlpha	boolean	Optional; defaults to "alpha" in color && color.alpha < 1	Whether to include alpha; by default included only when supplied and less than 1.

Returns

Value	Type	Description
result	string	Lowercase #rrggbb or #rrggbbaa text.

mixHexColors Blend

Linearly blends two hexadecimal colors, including alpha.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
first	string	Required	Color at amount = 0.
second	string	Required	Color at amount = 1.
amount	number	Required	Blend ratio from 0 to 1.

Returns

Value	Type	Description
result	string	Lowercase hexadecimal color; retains alpha if either input includes it.

mixHexColorWithBlack Blend

Blends toward black by a ratio.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
color	string	Required	Valid hexadecimal color.
amount	number	Required	Blend ratio from 0 to 1.

Returns

Value	Type	Description
result	string	Hexadecimal color blended with black; shares the blend function's argument and exception semantics.

mixHexColorWithWhite Blend

Blends toward white by a ratio.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
color	string	Required	Valid hexadecimal color.
amount	number	Required	Blend ratio from 0 to 1.

Returns

Value	Type	Description
result	string	Hexadecimal color blended with white; shares the blend function's argument and exception semantics.

relativeLuminance Luminance

Calculates WCAG sRGB relative luminance.

Signature

export function relativeLuminance(color: string): number;

Example

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

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

Input

Input	Type	Required / default	Description
color	string	Required	Valid hexadecimal color.

Returns

Value	Type	Description
result	number	Relative luminance from 0 to 1.

contrastRatio Contrast

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

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
first	string	Required	First hexadecimal color.
second	string	Required	Second hexadecimal color.

Returns

Value	Type	Description
result	number	Contrast ratio of the lighter and darker colors.

pickHigherContrastColor Contrast

Chooses the candidate with higher contrast against the background.

Signature

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

Example

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

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

Input

Input	Type	Required / default	Description
background	string	Required	Actual opaque background color.
first	unknown	Optional; defaults to "#000000"	First candidate; black by default.
second	unknown	Optional; defaults to "#ffffff"	Second candidate; white by default.

Returns

Value	Type	Description
result	string	Original candidate string with higher contrast; returns first on a tie.