Skip to main content

Utils

Functions​

achromatic()​

achromatic<Color>(color): boolean

Checks if a color token is achromatic (without hue or simply grayscale).

Type Parameters​

β€’ Color extends ColorToken

Parameters​

β€’ color: Color

The color token to test if it is achromatic or not.

Returns​

boolean

Example​

import { achromatic } from "huetiful-js";

achromatic('pink')
// false

let sample = [
"#164100",
"#ffff00",
"#310000",
'pink'
];

console.log(sample.map(achromatic));

// [false, false, false,false]

achromatic('gray')
// Returns true

// We can expand this example by interpolating between black and white and then getting some samples to iterate through.

import { interpolator } from "huetiful-js"

// we create an interpolation using black and white with 12 samples
let grays = interpolator(["black", "white"],{ num:12 });

console.log(grays.map(achromatic));

//
[false, true, true,
true, true, true,
true, true, true,
true, true, false
]

Defined in​

utils.ts:252


alpha()​

alpha<Color, Amount>(color, amount?): Amount extends undefined ? number : Color

Returns the color token's alpha channel value.

If the the amount parameter is passed in, it sets the color token's alpha channel with the amount specified and returns the color as a hex string.

tip
  • Also supports math expressions as a string for the amount parameter. For example *0.5 which means the value multiply the current alpha by 0.5 and set the product as the new alpha value. In short currentAlpha * 0.5 = newAlpha. The supported symbols are * - / +.

Type Parameters​

β€’ Color extends ColorToken

β€’ Amount

Parameters​

β€’ color: Color

The color with the opacity/alpha channel to retrieve or set.

β€’ amount?: Amount

The value to apply to the opacity channel. The value is between [0,1]

Returns​

Amount extends undefined ? number : Color

Example​

// Getting the alpha
console.log(alpha('#a1bd2f0d'))
// 0.050980392156862744

// Setting the alpha

let myColor = alpha('b2c3f1', 0.5)

console.log(myColor)

// #b2c3f180

Defined in​

utils.ts:85


complimentary()​

complimentary<Color, Options>(baseColor, options?): ColorToken

Returns the complimentary color of the passed in color token. A complimentary color is 180 degrees away on the hue channel.

Type Parameters​

β€’ Color extends ColorToken

β€’ Options extends ComplimentaryOptions

Parameters​

β€’ baseColor: Color

The color to retrieve its complimentary equivalent.

β€’ options?: Options

Optional overrides to customize behaviour.

Returns​

ColorToken

Example​

import { complimentary } from "huetiful-js";

console.log(complimentary("pink", true))
//// { hue: 'blue-green', color: '#97dfd7ff' }

console.log(complimentary("purple"))
// #005700

Defined in​

utils.ts:733


family()​

family<Color, HueFamily>(color): HueFamily

Gets the hue family which a color belongs to with the overtone included (if it has one.).

For example 'red' or 'blue-green'. If the color is achromatic it returns the string 'gray'.

Type Parameters​

β€’ Color extends ColorToken

β€’ HueFamily extends never

Parameters​

β€’ color: Color

The color to query its shade or hue family.

Returns​

HueFamily

Example​

import { family } from 'huetiful-js'

console.log(family("#310000"))
// 'red'

Defined in​

utils.ts:621


lightness()​

lightness<Color, Options>(color, options?): ColorToken

Darkens the color by reducing the lightness channel by amount of the channel. For example 0.3 means reduce the lightness by 0.3 of the channel's current value.

Type Parameters​

β€’ Color extends ColorToken

β€’ Options extends LightnessOptions

Parameters​

β€’ color: Color

The color to darken.

β€’ options?: Options

Returns​

ColorToken

Example​

import { lightness } from "huetiful-js";

// darkening a color
console.log(lightness('blue', 0.3, true));

// '#464646'

// brightening a color, we can omit the final param
// because it's false by default.
console.log(brighten('blue', 0.3));
//#464646

Defined in​

utils.ts:291


luminance()​

luminance<Color, Amount>(color, amount?): Amount extends number ? ColorToken : number

Gets the luminance of the passed in color token.

If the amount parameter is passed in, it will adjust the luminance by interpolating the color with black (to decrease luminance) or white (to increase the luminance) by the specified amount.

Type Parameters​

β€’ Color extends ColorToken

β€’ Amount

Parameters​

β€’ color: Color

The color to retrieve or adjust luminance.

β€’ amount?: number

The amount of luminance to set. The value range is normalised between [0,1]

Returns​

Amount extends number ? ColorToken : number

Example​

import { luminance } from 'huetiful-js'

// Getting the luminance

console.log(luminance('#a1bd2f'))
// 0.4417749513730954

console.log(colors('all', '400').map((c) => luminance(c)));

// [
0.3595097699638928, 0.3635745068550118,
0.3596908494424909, 0.3662525955988395,
0.36634113914916244, 0.32958967582076004,
0.41393242740130043, 0.5789820793721787,
0.6356386777636567, 0.6463720036841869,
0.5525691083297639, 0.4961850321908156,
0.5140644334784611, 0.4401325598899415,
0.36299191043315415, 0.3358285501372504,
0.34737270839643575, 0.37670102542883394,
0.3464512307705231, 0.34012939384198054
]

// setting the luminance

let myColor = luminance('#a1bd2f', 0.5)

console.log(luminance(myColor))
// 0.4999999136285792

Defined in​

utils.ts:553


mc()​

mc<Color, Value>(modeChannel): (color, value?) => Value extends string | number ? ColorToken : number

Sets the value of the specified channel on the passed in color.

If the amount parameter is undefined it gets the value of the specified channel.

Type Parameters​

β€’ Color extends ColorToken

β€’ Value

Parameters​

β€’ modeChannel: string

The mode and channel to be retrieved. For example 'rgb.b' will return the value of the blue channel in the RGB color space of that color.

Returns​

Function

Parameters​

β€’ color: Color

β€’ value?: string | number

Returns​

Value extends string | number ? ColorToken : number

Example​

import { mc } from 'huetiful-js'

console.log(mc('rgb.g')('#a1bd2f'))
// 0.7411764705882353

Defined in​

utils.ts:164


overtone()​

overtone<Color, Bias>(color): Bias | false

Returns the name of the hue family which is biasing the passed in color using the 'lch' colorspace.

  • If an achromatic color is passed in it returns the string 'gray'
  • If the color has no bias it returns false.

Type Parameters​

β€’ Color extends ColorToken

β€’ Bias extends ColorFamily

Parameters​

β€’ color: Color

The color to query its overtone.

Returns​

Bias | false

Example​

import { overtone } from "huetiful-js";

console.log(overtone("fefefe"))
// 'gray'

console.log(overtone("cyan"))
// 'green'

console.log(overtone("blue"))
// false

Defined in​

utils.ts:704


temp()​

temp<Color>(color): "cool" | "warm"

Returns a rough estimation of a color's temperature as either 'cool' or 'warm' using the 'lch' colorspace.

Type Parameters​

β€’ Color extends ColorToken

Parameters​

β€’ color: Color

The color to check the temperature. True if the color is cool else false.

Returns​

"cool" | "warm"

Example​

import { isCool } from 'huetiful-js'

let sample = [
"#00ffdc",
"#00ff78",
"#00c000"
];

console.log(isCool(sample[2]));
// false

console.log(map(sample, isCool));

// [ true, false, true]

Defined in​

utils.ts:668


token()​

token<Color, Options>(color, options?): ColorToken

Parses any recognizable color to the specified kind of ColorToken type.

The kind option supports the following types as options:

  • 'arr' - Parses the color token to an array of channel values with the colorspace as the first element if the omitMode parameter is set to false in the options object.

  • 'num' - Parses the color token to its numerical equivalent to a number between 0 and 16,777,215.

The numberType can be used to specify which type of number to return if the kind option is set to 'number':

  • 'hex' - Hexadecimal number
  • 'bin' - Binary number
  • 'oct' - Octal number
  • 'expo' - Decimal exponential notation
  • 'str' - Parses the color token to its hexadecimal string equivalent.

  • 'obj' - Parses the color token to a plain color object in the mode specified by the targetMode parameter in the options object.

  • 'temp' - Parses the color token to its RGB equivalent and expects the value to be between 0 and 30,000

tip

If the color token has an explicit alpha (specified by the alpha key in color objects and as the fourth and last number in a color array) the string will be 8 characters long instead of 6.

Type Parameters​

β€’ Color extends ColorToken

β€’ Options extends TokenOptions

Parameters​

β€’ color: Color

The color token to parse or convert.

β€’ options?: Options

Options to customize the parsing and output behaviour.

Returns​

ColorToken

Defined in​

utils.ts:344