KOLORWHEEL.JS

Introduction

What is it?

This small javascript library is designed for developers, who have no talent and time to create professional color palettes. Pick a base color, build a transformation chain, and if you haven't choosen too weird parameters, the result will be satisfactory.

Features

Try live examples!

In the examples below you can change some parameters. As you modify the code, it will be executed immediatelly.

The magic world of colors

The HSL color model

HSL cone (image: Wikipedia)

If you have ever seen a color picker before, you're probably familiar with the HSV or HSL color model. You may try Most Excellent HSL Color Picker, also don't miss the docs.

In the HSL model colors are defined by the following parameters:

Restrictions

Keep in mind, HSL color space is a cone-shaped coordinate system:

Hue order (image: Gamasutra)

That's why the most accurate 2D representation of the HSL color space is the triangle color picker (not explained here).

Do you know...

Do you know where does the hue order come from? The answer is pretty obvious, see figure. Or check this.

Defining colors

Constructors

HTML hex notation can be used in constructor, with or without hashmark.

When the constructor is an array, it's interpreted as array of H, S, L values.

Last, KolorWheel object can be created from another KolorWheel object.

Direct H, S, L access

You can access h, s and l properties directly.

Overlflow

Hue can't overflow, the wheel has no ends. You may also use negative numbers.

When saturation or lightness overflows, the value will be cut back in the 0..100 range.

Getting color value

In the examples we used getHex() method to get result in HTML notation format. There are also getHsl() and getRgb() methods, they will return array.

When the generated color is used as background, isDark() or isLight() helps to determine whether light or dark foreground color should be used. Note that these methods provide better result which can be achieved by checking value of the l (lightness) property.

Creating gradients

Basic gradient

The simplest way to create a gradient is to morph one color to another. The target of the morph operation is an absolute color, so we will use abs() method. This method handles the first parameter, which is the target color, as the constructor does: it can be HTML hex value, H, S, L array or another KolorWheel object. Second parameter is the length of the gradient, optional third parameter is the starting index.

Gradient methods, like abs() produces a series of KolorWheel objects, they can be accessed by calling get() method of the original object with the index of requested step as parameter.

Absolute gradient

When the first parameter of the abs() method is a number, the first three parameters are interpreted as hue, saturation and lightness. Special value of -1, occurs that it won't changed in the gradient items, all the result will have the same H, S or L value.

In this example, only hue is changed to the specified target absolute value, the saturation and lightness are keeping source color's values.

We used each() method there, it sets this to the actual KolorWheel element. The property named this.step holds the step index of the actual gradient.

Relative gradient

The rel() method's parameters are the final distance from the original values, in the usual hue, saturation, lightness order. Special value of 0 occurs that it won't changed, the result will inherit base color's H, S or L value.

Advanced techniques

Array parameters

As we've seen, the hue, saturation and lightness parameters of abs() and rel() can be numeric, or a special "won't change" value. There is another option: they can be also arrays.

When you define any of H, S, L parameters as array, abs() and rel() will pick next value from the array in each step.

If you don't define length, the gradient length value will be the longest of H, S, L arrays.

In this example, we've defined hue and saturation array same length, so the following triad moves together: 0° red with 100% saturation, 0° red with 40% saturation and 45° orange with 100% saturation. Meanwhile, lightness is morphing to 80%, in 9 steps.

Applying colors on elements

Until now, we've used paintBox() function to display results, but in the wild, we have to apply colors on existing DOM elements. Everyone's using jQuery, so KolorWheel.js supports it.

When the length parameter of abs() or rel() is replaced by a jQuery selector function result, the gradient length will be the length of the result it. Then, you will get jQuery items in the parameter of the each() method.

 A    B    C    D    E    F    G    H    I    J    K    L    M    N    O    P    Q    R    S    T    U    V  

When you want to apply two different KolorWheel gradient on the same jQuery result set, you can refer to external KolorWheel result items in the each() callback by using external color's get() method with this.step.

The KolorWheel result lists should be the same length, but that's not a problem, because you can use the same jQuery selector result on the external KolorWheels as the gradient method length parameter.

 B    C    D    E    F    G    H    I    J    K    L    M    N    O    P    Q    R    S    T    U    V    W  

Nesting

There is only one new thing comes into the picture: abs() and rel() have yet another parameter, which describes how many leading items should be omitted. When you use outer loop's result, it's useful to skip inner loop's first result item, because it's the same as the outer item.

Chaining

Gradient methods can be chained. When applying a method on a base result set, it replaces each item with a new result list.

In this example, the abs() method flip/flops between 0° red and 270° blue meanwhile morphing into 25% saturated grayish, in 8 steps. These colors are the 1st and 6th columns.

The chained rel() method picks this 8 items, and replaces each with 5 items, which gets lighter by 40%.

The result is 8 * 5 = 40 items.

Pointless further examples

Fading out

Different grays

Pepita