Collection

Functions

filterBy()

filterBy(collection, options): Collection

Filters a collection of colors using the specified factor as the criterion.

tip

• The factor is expected to be an array of strings with each element being a valid factor. Every key is a factor, with the filtered collection as the value in the result object.

To get all the factors in the result object pass undefined to factor.

The supported options are:

• 'contrast' - Returns colors with the specified contrast range. The contrast is tested against a comparison color (the 'against' param) and the specified contrast ranges.

• 'lightness' - Returns colors in the specified lightness range.

• 'chroma' - Returns colors in the specified saturation or chroma range. The range is internally normalized to the supported ranges by the colorspace in use if it is out of range.

• 'distance' - Returns colors with the specified distance range. The distance is tested against a comparison color (the 'against' param) and the specified distance ranges. Uses the differenceHyab metric for calculating the distances.

• luminance - Returns colors in the specified luminance range.

• 'hue' - Returns colors in the specified hue ranges between 0 to 360.

tip

For the chroma and lightness factors, the range is internally normalized to the supported ranges by the colorspace in use if it is out of range. This means a value in the range [0,1] will return, for example if you pass startLightness as 0.3 it means 0.3 (or 30%) of the channel's supported range. But if the value of either start or end is above 1 AND the colorspace in use has an end range higher than 1 then the value is treated as is else the value is treated as if in the range [0,100] and will return the normalized value.

See the color spaces page for the expected ranges.

Supports expression strings e.g '>=0.5'. The supported symbols are == | === | != | !== | >= | <= | < | >

Parameters

• collection: Collection = []

The collection of colors to filter.

• options: FilterByOptions = ...

Options to customise filtering behaviour.

Returns

Collection

Example

import { filterBy } from 'huetiful-js'

let sample = [
'#00ffdc',
'#00ff78',
'#00c000',
'#007e00',
'#164100',
'#ffff00',
'#310000',
'#3e0000',
'#4e0000',
'#600000',
'#720000',
]

Defined in

collection.ts:408

---

sortBy()

sortBy(collection, options): Collection

Sorts colors according to the specified factor. The supported options are:

tip

• The factor is expected to be an array of strings with each element being a valid factor. Every key is a factor, with the sorted collection as the value in the result object.

To get all the factors in the result object pass undefined to factor.

• 'contrast' - Sorts colors according to their contrast value as defined by WCAG. The contrast is tested against a comparison color which can be specified in the options object.
• 'lightness' - Sorts colors according to their lightness.
• 'chroma' - Sorts colors according to the intensity of their chroma in the colorspace specified in the options object.
• 'distance' - Sorts colors according to their distance. The distance is computed from the against color token which is used for comparison for all the colors in the collection.
• luminance - Sorts colors according to their relative brightness as defined by the WCAG3 definition.

tip

The return type is determined by the type of collection:

• Plain objects are returned as Map objects because they remember insertion order. Map objects are returned as is.
• ArrayLike objects are returned as plain arrays. Plain arrays are returned as is.

Parameters

• collection: Collection = []

The collection of colors to sort.

• options: SortByOptions = ...

The optional overrides to customize the sorting behaviour.

Returns

Collection

Example

import { sortBy } from 'huetiful-js'

let sample = ['purple', 'green', 'red', 'brown']
console.log(
 sortBy(sample,{ against:'yellow' kind:['distance'],order:'desc',})
)

// [ 'brown', 'red', 'green', 'purple' ]

Defined in

collection.ts:259

---

stats()

stats(collection, options): Stats

Computes statistical values about the factors the passed in collection.

The properties from each returned factor object are:

• against - The color being used for comparison. Required for the distance and contrast factors. If relativeMean is false, other factors that take the comparison color token as an overload will have this property's value as null.

• colorspace - The colorspace in which the factors were computed in. It has no effect on the contrast or distance factors (for now).

• extremums - An array of the minimum and the maximum value (respectively) of the factor.

• colors - An array of color tokens that have the minimum and maximum extremum values respectively.

• mean - The average value for the factor.

tip

The mean property can be overloaded by the relativeMean option:

• If relativeMean is true, the against option will be used as a subtrahend for calculating the distance between each extremum. For example, it will mean "Get the largest/smallest distance between factor as compared against this color token otherwise just get the smallest/largest factor from thr passed in collection."

These properties are available at the topmost level of the resultant object:

• achromatic - The amount of colors which are gray out of the total colors in the collection as a value in the range [0,1].
• colorspace - The colorspace in which the values were computed from, expected to be hue based. Defaults to lch if an invalid mode like rgb is used.

tip

• The factor is expected to be an array of strings with each element being a valid factor. Every key is a factor, with the stats of that factor as the value in the result object.

To get all the factors in the result object pass undefined to factor.

Parameters

• collection: Collection = []

The collection to compute stats from. Any collection with color tokens as values will work.

• options: StatsOptions = ...

The optional overrides to customize the computing behaviour for the factors.

Returns

Stats

Defined in

collection.ts:74