jQuery xcolor is a color parser and manipulation library for jQuery. It accepts hexadecimal values, CSS color names, RGB, HSL, and HSV input, then exposes conversions, color mixing, palette generation, animation hooks, and text colorization through a single $.xcolor API.
The plugin began as the JavaScript successor to the earlier server-side PHP color class of the same name. Moving color calculations into the browser put them next to the interface code that consumed them, while the rewrite retained the PHP version's feature set and added browser-specific operations. Its original design priorities were speed and numerical accuracy, backed by unit tests for the supported representations and transformations.
The plugin predates native CSS color interpolation and modern color libraries, but remains useful when maintaining jQuery applications that depend on its permissive parser or its particular mixing operations. The parser accepts CSS-style values such as #3498cd, rgba(20, 90, 90, 0.6), and named colors. It also accepts xcolor's nonstandard hsv() and hsb() forms.
Color Workbench
Enter any supported color and choose an operation. Unary methods use the first color; mixing, distance, and readability methods use both. Palette methods return every generated color.
Basic Usage
Load jQuery first, followed by xcolor:
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="jquery.xcolor.min.js"></script> A parsed color object can be converted into several representations:
const color = $.xcolor.test('rgba(20, 90, 90, 0.6)');
console.log(color.getHex());
console.log(color.getRGB());
console.log(color.getHSL());
console.log(color.getHSV());
console.log(color.getCSS()); Invalid input makes $.xcolor.test() return null. Other operations follow the same convention, which makes validation before accessing a result important.
Color Object Methods
- getRGB() returns red, green, blue, and alpha components.
- getHSL() and getHSV() return cylindrical color-model components.
- getHex() returns a six-digit hexadecimal color without alpha.
- getCSS() returns an rgb(), rgba(), or transparent CSS value.
- getInt(), getArray(), and getFraction() expose numeric forms.
- getName() finds the nearest built-in color name using the library's HSL distance.
- getColor(type) selects a representation; toString() delegates to getHex().
- setColor(value) reparses a value into the existing mutable color object.
Manipulation API
| Method | Behavior |
|---|---|
| $.xcolor.red(color) | Keeps red and sets green and blue to 255; $.xcolor.green() and $.xcolor.blue() behave analogously. |
| $.xcolor.greyfilter(color, formula) | Produces grayscale using one of three weighted formulas. |
| $.xcolor.sepia(color) | Applies the plugin's weighted sepia matrix to the RGB channels. |
| $.xcolor.inverse(color) | Inverts all three RGB channels with a bitwise operation. |
| $.xcolor.complementary(color) | Rotates HSL hue by 180 degrees. |
| $.xcolor.lighten(color, step, shade) | Adds step * shade to each RGB channel; $.xcolor.darken() subtracts it. |
| $.xcolor.webround(color) | Rounds channels to the legacy web-safe palette. |
| $.xcolor.random() | Builds an RGB color from three calls to Math.random(). |
Mixing and Palettes
| Method | Behavior |
|---|---|
| $.xcolor.gradientlevel(a, b, position, size) | Interpolates RGB channels between two colors. |
| $.xcolor.gradientarray(colors, position, size) | Interpolates across a multi-stop array of colors. |
| $.xcolor.opacity(base, overlay, alpha) | Composites the second color over the first using the supplied opacity. |
| $.xcolor.additive(a, b) | Adds channels and clamps them at 255. |
| $.xcolor.subtractive(a, b) | Adds channels minus 255 and clamps them at zero. |
| $.xcolor.multiply(a, b) | Multiplies normalized RGB channels. |
| $.xcolor.average(a, b) | Returns the channel-wise arithmetic mean. |
| $.xcolor.combine(a, b) | Combines channels with bitwise XOR. |
| $.xcolor.breed(a, b) | Randomly takes four-bit channel portions from either input. |
| $.xcolor.subtract(a, b) | Subtracts the second color's channels and clamps at zero. |
| $.xcolor.triad(color) | Returns three channel-permuted colors; $.xcolor.tetrad() returns four. |
| $.xcolor.analogous(color, results, slices) | Samples neighboring HSV hues. |
| $.xcolor.monochromatic(color, results) | Varies HSV value while retaining hue and saturation. |
| $.xcolor.splitcomplement(color) | Returns the source and two hue-shifted complements. |
Readability and Distance
$.xcolor.distance(a, b) uses a fast weighted Euclidean distance in encoded RGB space. It is useful for rough comparisons, but it is not a perceptually uniform metric such as CIEDE2000.
$.xcolor.readable(background, text, size) uses the plugin's historical luminance-difference heuristic. It is not a WCAG contrast calculation and should not be used as an accessibility conformance test. The workbench reports both the legacy result and the WCAG relative-luminance contrast ratio so the distinction is visible.
jQuery Extensions
$(element).readable() finds the effective foreground and background colors of the first matched element, then applies the same historical readability heuristic described above.
$(element).colorize(from, to, method) wraps individual text characters in spans and assigns interpolated colors. Built-in distribution methods are gradient, flip, and pillow; a callback may return any interpolation position from 0 to 1.
$('.title').colorize('burntsienna', '#0066ff', 'pillow'); The plugin also installs jQuery CSS hooks for foreground, background, border, and outline colors. This allows old jQuery animation code to interpolate colors, including xcolor's semicolon-separated multi-stop syntax.
$('.notice').animate({
backgroundColor: 'native; #0066ff; red; native'
}, 2000);