Welcome to Flexi ColorPicker Documentation. This document describes the usage and API of the color picker. The library was built with simplicity in mind so there should not be anything what can surprise you.
The color picker is built on top of HSV color model. The only two parts of the picker is therefore the slider, which allows you to select "hue" and the picker for selecting "saturation" and "value". Both the slider and the picker have to be specified as HTML elements. The main advantage is that their dimensions can be set in CSS. The color picker is not dependent on any external library or CSS stylesheet. You get all the functionality by including only one tiny JavaScript file (see example below).
Once you have your markup ready and CSS width and height set for both the slider and picker, the only thing you have to do is to instantiate the "ColorPicker" object. You can do that by calling the ColorPicker() function passing the slider, the picker element and callback as arguments. The callback is called whenever the color changes and it is passed color in hexadecimal, hsv and rgb formats. Hexadecimal format is the string used most commonly in CSS. Hsv and Rgb are objects with these properties: hsv: { h: /* hue [0,359] (angle) */, s: /* saturation [0,1] */, v: /* value [0,1] */ } rgb: { r: /* red [0,255] */, g: /* green [0,255] */, b: /* blue [0,255] */ }
<html>
<head>
<script type="text/javascript"
src="colorpicker.js"></script>
<style type="text/css">
#picker { width: 200px; height: 200px }
#slide { width: 30px; height: 200px }
</style>
</head>
<body>
<div id="picker"></div>
<div id="slide"></div>
<script type="text/javascript">
ColorPicker(
document.getElementById('slide'),
document.getElementById('picker'),
function(hex, hsv, rgb) {
console.log(hsv.h, hsv.s, hsv.v);
console.log(rbg.r, rgb.g, rgb.b);
document.body.style.backgroundColor = hex;
});
</script>
</body>
</html>
Note that you can set arbitrary dimensions, position, border and other CSS properties to the slider and picker element as you would do with any other HTML element on the page.
Flexi color picker allows you to set indicators - elements indicating the currently selected color. Following the Flexi color picker philosophy, there is no built-in images for the indicators. Instead, user has freedom to use any element he wants. It could be an img tag, div tag or any other object which can then be styled in CSS the usual way.
The user is expected to create a wrapper around the picker and picker indicator and another wrapper for the slide and slide indicator. The wrapper has to be a positioned element (in CSS: position relative/absolute/fixed). The ColorPicker passes coordinates of the indicators as arguments into the callback. The user can therefore set the left/top coordinate of an indicator inside the callback (assuming the indicator is absolutely positioned).
As the common usage is to center the indicator around the indicator position, the ColorPicker provides a helper function to do that to save the user from typing. See below an example and implementation of the helper for the curious ones.
<style type="text/css">
#picker-wrapper {
width: 200px;
height: 200px;
position: relative;
}
#slide-wrapper {
width: 30px;
height: 200px;
position: relative;
}
#picker-indicator {
width: 3px;
height: 3px;
position: absolute;
border: 1px solid white;
}
#slide-indicator {
width: 100%;
height: 10px;
position: absolute;
border: 1px solid black;
}
</style>
<div id="picker-wrapper">
<div id="picker"></div>
<div id="picker-indicator"></div>
</div>
<div id="slide-wrapper">
<div id="slide"></div>
<div id="slide-indicator"></div>
</div>
<script type="text/javascript">
ColorPicker(document.getElementById('slide'), document.getElementById('picker'),
function(hex, hsv, rgb, mousePicker, mouseSlide) {
ColorPicker.positionIndicators(
document.getElementById('slide-indicator'),
document.getElementById('picker-indicator'),
mouseSlide, mousePicker
);
document.body.style.backgroundColor = hex;
});
</script>
Note that it is not necessary to use the helper to position the indicators. As you can see below the implementation is straigtforward.
ColorPicker.positionIndicators = function(slideIndicator, pickerIndicator, slideIndicatorPosition, pickerIndicatorPosition) {
if (slideIndicatorPosition) {
pickerIndicator.style.left = ''; // reset the left coordinate
pickerIndicator.style.top = '0px';
pickerIndicator.style.right = '0px';
slideIndicator.style.top = (slideIndicatorPosition.y - slideIndicator.offsetHeight/2) + 'px';
}
if (pickerIndicatorPosition) {
pickerIndicator.style.top = (pickerIndicatorPosition.y - pickerIndicator.offsetHeight/2) + 'px';
pickerIndicator.style.left = (pickerIndicatorPosition.x - pickerIndicator.offsetWidth/2) + 'px';
}
};
The color of the color picker can also be set in the program instead of by the user mouse clicks. The usage is straightforward. The ColorPicker instance provides three methods: setHsv(hsvObject), setRgb(rgbObject) and setHex(hexString). See example below as it describes it better.
var c = ColorPicker( ... );
c.setHsv({ h: 310, s: .3, v: .7 }); // hue is an angle <0..359>
c.setRgb({ r: 230, g: 150, b: 30 }); // integer range <0..255>
c.setRgb({ r: .7, g: .2, b: .5 }); // float range <0..1>
c.setHex('#223344'); // usual HTML hex color string