R9Picker :: Documentation

Demo

Type: Complete

Type: Basic

Type: Minimal

Type: Unique

Some customizations example

Dark mode

Classic mode

Alpha channel

Name on palette

*Click on "Set" to change the UI color (It is not the default action of the "Set" button! I am just to demonstrating the change of the UI color using this button).

Some events example

Picking

Picking end

Set

Input

Saved

Getting started

Rainbow9 Picker (R9Picker) is a web color picker component created using the Rainbow9 (R9) color library.

Adding the library

You can download the library and host it or you can use it through jsDelivr.

jsDelivr

Add the following line to the your html:


<script src="https://cdn.jsdelivr.net/gh/hms-douglas/rainbow9picker@1.0.0/dist/r9picker.min.js"></script>

Download

Download the file here.

R9Picker

Name	Type	Description
containerSelector	String	The html element selector that will hold the color picker. It is recommended to use a different container for each color picker.
pickerType	R9Picker.TYPE constant	The type of color picker to be created.

Example


const picker1 = new R9Picker("#container", R9Picker.TYPE.COMPLETE);

const picker2 = new R9Picker("#container + div", R9Picker.TYPE.BASIC);

//If a simple string is passed it is considered as an ID, therefore "container" = "#container"
const picker3 = new R9Picker("container", R9Picker.TYPE.MINIMAL);

//If case of null, will use the body as container. NOT RECOMMENDED!
const picker3 = new R9Picker(null, R9Picker.TYPE.UNIQUE);

TYPE

The type of color picker to be created. All types can be checked on this example.

Name	R9Picker constant	Details	Example
Complete	R9Picker.TYPE.COMPLETE	Color picker with all features available.	Show
Basic	R9Picker.TYPE.BASIC	Does not contain: input fields; recent tabs; old color; button to restore color; set and cancel button.	Show
Minimal	R9Picker.TYPE.MINIMAL	The same as R9Picker.TYPE.BASIC, but without the bottom bar and the saved tab.	Show
Unique	R9Picker.TYPE.UNIQUE	Only one tab showing. The user cannot navigate between the tabs, the shown tab needs to be set by internal code.	Show

Methods

Color

Related to the current color. The default color is #147097.

COLOR

Variable used to set or get the current color.

As set: accepts colors in all strings format available in the R9 library. You can check the string formats here. This does not trigger any event!

As get: returns an object with the current color (in all color spaces accepted) in string format.

Example


//To set the color
picker.COLOR = "#FF0000";

//To set the color
picker.COLOR = "rgba(163, 56, 63, 0.5)";

//To get the current picked color in all formats:
picker.COLOR;
/*
Returns: 
    {
        rgb: "rgb(20, 112, 151, 128)",
        cmyk: "cmyk(87%, 26%, 0%, 41%, 128)",
        hsl: "hsl(198°, 77%, 34%, 128)",
        hsv: "hsv(198°, 87%, 59%, 128)",
        Lab: "Lab(44.2, -11.1, -28.3, 128)",
        hex: "#14709780"
    }
*/

//To get the current picked color in hex:
picker.COLOR.hex;
//Returns: '#14709780'

setColor()

Set/change the current color.

Name	Type	Required	Description
color	String (See formats)	Yes	The color, in string format, to be set as the current one. This does not trigger any event!

Example


picker.setColor("#FF0000");

picker.setColor("rgba(163, 56, 63, 0.5)");

Size

Related to the picking are size (width and height, aspect ratio of 1:1). The default size of the picking is 202 px.

SIZE

Variable used to set or get the width/height of the picking area.

As set: accepts a number.

As get: returns the size number.

Example


//To set the picking area size
picker.SIZE = 300;

//To get the current picking area size
picker.SIZE;
//Returns: 300

setSize()

Set/change the current picking area width/height.

Name	Type	Required	Description
size	Number	Yes	The number (pixels) for the width/height of the picking area.

Example


picker.setSize(300);

Visibility

Related to the visibility of the color picker element or the color picker container element.

hide()

To hide the element from view. By default it will hide the color picker element, not the color picker container element.

Name	Type	Required	Description
hideContainer	Boolean	No	In case of true will hide the container element instead of the color picker element.

Example


//Hides the color picker element
picker.hide();

//Hides the color picker container element.
picker.hide(true);

show()

To show the element. By default it will show the color picker element, not the color picker container element.

Name	Type	Required	Description
showContainer	Boolean	No	In case of true will show the container element instead of the color picker element.

Example


//Shows the color picker element
picker.show();

//Shows the color picker container element.
picker.show(true);

toggle()

Shows the element if it is hidden or hide the element if it is being shown. By default it will show/hide the color picker element, not the color picker container element.

Name	Type	Required	Description
toggleContainer	Boolean	No	In case of true will show/hide the container element instead of the color picker element.

Example


//Shows/hides the color picker element
picker.toggle();

//Shows/hides the color picker container element.
picker.toggle(true);

isShowing()

Type	Description
Boolean	Whether the color picker is being shown or not.

Example


picker.isShowing();
//Returns: true

Tab

Related to the tabs ("screens").

TAB

Constant with all tabs available. Each tab represents a "screen" in the color picker.

Name	R9Picker constant	Details
Square	R9Picker.TAB.SQUARE	The default tab. Shows a squared color picker.
Triangle	R9Picker.TAB.TRIANGLE	Shows a triangular color picker. This tab is under beta mode, therefore it can present wrong results. By default this tab is hidden.
Circle	R9Picker.TAB.CIRCLE	Shows a circular color picker. This tab is under beta mode, therefore it can present wrong results. By default this tab is hidden.
Scheme	R9Picker.TAB.SCHEME	Shows a harmony palette for the color picked, includes the harmonies/schemes: complementary; split complementary; triadic; tetradic; square; analogous; monochromatic; shades; tints and tones.
Palette	R9Picker.TAB.PALETTE	Shows the palettes set by you. See Palette.
Saved	R9Picker.TAB.SAVED	Shows all colors saved by the user. No methods available to change this palette. The colors are saved in the browser localstorage. This tab is not available in the type R9Picker.TYPE.UNIQUE. See Saved.
Recents	R9Picker.TAB.RECENT	Shows all colors set by the user during the "current session". No methods available to change this palette. This tab is not available in the type R9Picker.TYPE.UNIQUE. See Recents.

ACTIVE_TAB

Variable indicating the current tab being shown.

Example


picker.ACTIVE_TAB;
//Returns "square" //Equivalent to R9Picker.TAB.SQUARE

goToTab()

Shows the desired tab without user interaction. If the tab is hidden, this method will not work.

Name	Type	Required	Description
tab	R9Picker.TAB constant	Yes	The desired tab to be shown.

Example


picker.goToTab(R9Picker.TAB.SAVED);

picker.goToTab(R9Picker.TAB.RECENT);

hideTab()

Hides the tab button, but keep all elements. Can be undone. Cannot hide the active tab.

Name	Type	Required	Description
tab	R9Picker.TAB constant	Yes	The desired tab to be hidden.

Example


picker.hideTab(R9Picker.TAB.SAVED);

picker.hideTab(R9Picker.TAB.RECENT);

unhideTab()

Unhides the tab button.

Name	Type	Required	Description
tab	R9Picker.TAB constant	Yes	The desired tab to unhide.

Example


picker.unhideTab(R9Picker.TAB.SAVED);

picker.unhideTab(R9Picker.TAB.RECENT);

removeTab()

Removes the tab button and all its elements and features. Cannot be undone! Cannot remove the active tab.

Name	Type	Required	Description
tab	R9Picker.TAB constant	Yes	The desired tab to be removed.

Example


picker.removeTab(R9Picker.TAB.SAVED);

picker.removeTab(R9Picker.TAB.RECENT);

Alpha

Related to the alpha channel.

setAlphaEnabled()

Enables/Disables the alpha channel of the color picker.

Name	Type	Required	Description
b	Boolean	Yes	In case of false the alpha channel picker bar and the inputs are still displayed, but are disabled. This does not affect the Color variable.

Example


//To enable the alpha channel
picker.setAlphaEnabled(true);

//To disable the alpha channel
picker.setAlphaEnabled(false);

isAlphaEnabled()

Type	Description
Boolean	Whether the alpha channel is enabled or not.

Example


picker.isAlphaEnabled();
//Returns: true

Dark mode

Related to the dark mode. By default the color picker is shown in the light mode.

setDarkMode()

Enables/Disables the dark mode.

Name	Type	Required	Description
b	Boolean	Yes	In case of true enables the dark mode.

Example


//To enable the dark mode
picker.setDarkMode(true);

//To disable the dark mode
picker.setDarkMode(false);

isDarkMode()

Type	Description
Boolean	Whether the color picker is in dark mode or not.

Example


picker.isDarkMode();
//Returns: false

Classic mode

Related to the style of the color picker. Classic mode is a style with minimum design. By default the classic mode is disabled.

setClassic()

Enables/Disables the classic mode.

Name	Type	Required	Description
b	Boolean	Yes	In case of true enables the classic mode.

Example


//To enable the classic mode
picker.setClassic(true);

//To disable the classic mode
picker.setClassic(false);

isClassic()

Type	Description
Boolean	Whether the color picker is in the classic mode or not.

Example


picker.isClassic();
//Returns: false

UI color

Related to the main UI color (icons, buttons, ranges and some text). The default UI color is #147097.

UI_COLOR

Variable used to set or get the main UI color.

As set: accepts colors in all string format available in the R9 library. You can check the string formats here. Alpha channel is ignored.

As get: returns an object with the current main UI color (in all color spaces accepted) in string format.

Example


//To set the main UI color
picker.UI_COLOR = "red";

//To set the main UI color
picker.UI_COLOR = "hsl(122°, 61%, 46%)"

//To get the main UI color in all formats:
picker.UI_COLOR;
/*
Returns:
    {
        rgb: "rgb(46, 189, 51)",
        cmyk: "cmyk(76%, 0%, 73%, 26%)",
        hsl: "hsl(122°, 61%, 46%)",
        hsv: "hsv(122°, 76%, 74%)",
        Lab: "Lab(67.1, -65.7, 61.1)",
        hex: "#2EBD33"
    }
*/

//To get the main UI color in rgb format:
picker.UI_COLOR.rgb;
//Returns: 'rgb(46, 189, 51)'

setUiColor()

Set/change the main UI color. Alpha channel is ignored.

Name	Type	Required	Description
color	String (See formats)	Yes	The color, in string format, to be set as the main UI color.

Example


picker.setUiColor("red");

picker.setUiColor("rgb(46, 189, 51)");

Palette

Related to color palette. By default no palettes are set. The palette tab will show "Empty" if no palette is set.

PALETTE

The library contains 4 built-in palettes that can accessed using the R9Picker.PALETTE constant.

R9Picker constant	Amount of colors	Description
R9Picker.PALETTE.CLASSIC	11	Basic colors.
R9Picker.PALETTE.CLASSIC_LIGHT	11	Basic light colors.
R9Picker.PALETTE.MATERIAL_DESIGN	19	2014 material design colors (variant 500).
R9Picker.PALETTE.HUE_24	24	Hue range splitted into 24 colors.

CLASSIC (colors)

CLASSIC_LIGHT (colors)

MATERIAL_DESIGN (colors)

HUE_24 (colors)

addPalette()

Adds a color palette.

Name	Type	Required	Description
palette	Array or R9Picker.PALETTE constant	Yes	An array with all the colors that compose the palette. The colors must be in string format (See formats).

Type	Description
Number	The palette's ID.

Example


//To add a R9Picker constant palette
picker.addPalette(R9Picker.PALETTE.MATERIAL_DESIGN);
//Returns: 48 //Example of id returned

//To add a custom palette
picker.addPalette(["red", "green", "rgb(0, 0, 255)", "#FEFE00"]);
//Returns: 50 //Example of id returned

getPalette()

Gets a specific color palette.

Name	Type	Required	Description
id	Number	Yes	The palette's ID.

Type	Description
Array	An array with all the colors, in hex format, of the palette.

Example


    //To get palette with ID 48
    picker.getPalette(48);
    //Returns: ['#F44336FF', '#E91E63FF', '#9C27B0FF', '#673AB7FF', '#3F51B5FF', '#2196F3FF', '#03A9F4FF', '#00BCD4FF', '#009688FF', '#4CAF50FF', '#8BC34AFF', '#CDDC39FF', '#FFEB3BFF', '#FFC107FF', '#FF9800FF', '#FF5722FF', '#795548FF', '#9E9E9EFF', '#607D8BFF']

    //To get palette with ID 50
    picker.getPalette(50);
    //Returns: ['#FF0000FF', '#008000FF', '#0000FFFF', '#FEFE00FF']

getPalettes()

Gets all color palettes added to the color picker.

Type	Description
Object	An object with all the palettes added to the color picker. The key corresponds to the palette's ID. The value is an array with all the colors in hex format.

Example


picker.getPalettes();
/*
Returns:
    {
        "48": [
            "#F44336FF",
            "#E91E63FF",
            "#9C27B0FF",
            "#673AB7FF",
            "#3F51B5FF",
            "#2196F3FF",
            "#03A9F4FF",
            "#00BCD4FF",
            "#009688FF",
            "#4CAF50FF",
            "#8BC34AFF",
            "#CDDC39FF",
            "#FFEB3BFF",
            "#FFC107FF",
            "#FF9800FF",
            "#FF5722FF",
            "#795548FF",
            "#9E9E9EFF",
            "#607D8BFF"
        ], "50": [
        "#FF0000FF",
        "#008000FF",
        "#0000FFFF",
        "#FEFE00FF"
        ]
    }
*/

updatePalette()

Changes the colors of a palette.

Name	Type	Required	Description
id	Number	Yes	The palette's ID.
palette	Array or R9Picker.PALETTE constant	Yes	An array with all the colors that compose the palette. The colors must be in string format (See formats).

Example


//To update a palette with ID 48
picker.updatePalette(48, R9Picker.PALETTE.HUE_24);

//To update a palette with ID 50
picker.updatePalette(50, ["red", "green", "blue", "#FEFE00"]);

removePalette()

Removes a specific palette from the color picker.

Name	Type	Required	Description
id	Number	Yes	The palette's ID.

Example


//To remove palette with ID 48
picker.removePalette(48);

//To remove palette with ID 50
picker.removePalette(50);

removeAllPalettes()

Removes all palettes from the color picker.

Example


//To remove all palettes added
picker.removeAllPalettes();

showColorNameOnPalette()

Whether to show, or hide, the color name (in hex format) from all palettes, including from the recents, saved and scheme tabs. By default the color name is hidden.

Name	Type	Required	Description
b	Boolean	Yes	If true the color name (in hex format) will be shown.

Example


//To show the color name in all palettes
picker.showColorNameOnPalette(true);

//To hide the color name from all palettes
picker.showColorNameOnPalette(false);

isShowingColorNameOnPalette()

Type	Description
Boolean	Whether the color name is being shown in the palettes.

Example


picker.isShowingColorNameOnPalette();
//Returns: false

Recents

Related to the recents colors used by the user.

When the user click on the button "Set" the current color is added to the recents tab.

All color pickers added in the same page share this data.

The colors from the recent tab are saved in a variable, therefore they are removed when the user refreshes the page, and are not shared between browser's tabs.

getRecents()

Gets all the colors from the recent tab palette. This methods belongs to the class not the object, however it can accessed, as a shortcut, though the object.

Type	Description
Array	An array with all the colors, in hex format, of the recent palette.

Example


R9Picker.getRecents();
//Returns: ['#147097FF', '#3A5A68FF', '#DE24DDFF', '#DE238AFF', '#DEC823FF']

picker.getRecents();
//Returns: ['#147097FF', '#3A5A68FF', '#DE24DDFF', '#DE238AFF', '#DEC823FF']

Saved

Related to the saved colors by the user.

When the user click on the save button the current color is added to the saved tab.

The colors from the saved tab are saved in the localstorage (key: "r9-picker-saved"), therefore all color pickers share the same saved palette.

The user can unsave a color by click on it while holding the "Shift" key.

getSaved()

Gets all the colors from the saved tab palette. This methods belongs to the class not the object, however it can accessed, as a shortcut, though the object.

Type	Description
Array	An array with all the colors, in hex format, of the saved palette.

Example


R9Picker.getSaved();
//Returns: ['#99D9EAFF', '#2F8EA8FF', '#475E65FF', '#3498B4FF']

picker.getSaved();
//Returns: ['#99D9EAFF', '#2F8EA8FF', '#475E65FF', '#3498B4FF']

PICKER

Variable holding the color picker html element.

Example


//To get the color picker html element
picker.PICKER;
//Returns: <div r9>...</div>

CONTAINER

Variable holding the color picker html container element.

Example


//To get the color picker html container element
picker.CONTAINER;
//Returns: <div id="container">...</div>

Events

Related to event listeners.

EVENT

The events listeners available for the color picker. Some events can be check on this example.

R9Picker constant	Trigger(s)	Callback parameter(s)
R9Picker.EVENT.VISIBILITY	- When the visibility (hide/show) of the color picker element, or container, changes, either by user action or by code (See Visibility).	Boolean (true if showing, false if hidden).
R9Picker.EVENT.TAB_CHANGE	- When a new tab is "selected", either by user action or by code (See Tab).	String (tab name. See Tab).
R9Picker.EVENT.PICKING	- When the user drags the color selectors inside the picking area.	Object COLOR (only as getter).
R9Picker.EVENT.PICKING_END	- When the user release the mouse (mouseup) after dragging inside the picking area; - When the previous color is restored; - When the EyeDropper is used; - When a color from any palette is picked; - Right after the input event is triggered.	Object COLOR (only as getter).
R9Picker.EVENT.CANCELED	- When the user clicks the "Cancel" button.	-
R9Picker.EVENT.SET	- When the user clicks the "Set" button.	Object (key "current": object representing the current color; key "previous": object representing the previous color set. Both internal objects are equal to the COLOR object).
R9Picker.EVENT.COLOR_SAVED	- When the user clicks the save button (See Saved).	Object (key "color": object representing the color added to the palette; key "palette": array with objects representing the color palette (including the color added). All internal objects are equal to the COLOR object).
R9Picker.EVENT.COLOR_UNSAVED	- When the user removes a color from the saved palette (See Saved).	Object (key "color": object representing the color removed from the palette; key "palette": array with objects representing the color palette (does not includes the color removed). All internal objects are equal to the COLOR object).
R9Picker.EVENT.INPUT	- When the user presses (keydown) the "Enter" key while an input of the color picker is focused.	Object (key "space": string representing the color space changed (e.g. "RGB"); key "letter": string representing the letter from the color space changed (e.g. "R" from "RGB"); key "value": number or string representing the value typed for the corresponding "letter"; key "color": object representing the color set (equals to the COLOR object)).

addEventListener()

Adds an event listener to the color picker.

The same event can be added multiple times. Each event added will have an ID.

Name	Type	Required	Description
event	R9Picker.EVENT constant	Yes	The event that will trigger the callback.
callback	Function	Yes	The action to be executed when the event set is triggered.

Type	Description
Number	The event's ID.

Example


//To add an input event
picker.addEventListener(R9Picker.EVENT.INPUT, (data) => {
    console.log(data.space);
    //Might print (when triggered): "HSV" //Example
});
//Returns: 53 //Example of id returned

//To add a set event
picker.addEventListener(R9Picker.EVENT.SET, (data) => {
    console.log(data);
    /*
    Might print (when triggered) //Example:
        {
            current: {
                rgb: "rgb(143, 29, 213, 255)",
                cmyk: "cmyk(33%, 86%, 0%, 16%, 255)",
                hsl: "hsl(277°, 76%, 47%, 255)",
                hsv: "hsv(277°, 86%, 84%, 255)",
                Lab: "Lab(40, 72.9, -70.8, 255)",
                hex: "#8F1DD5FF"
            },
            previous: {
                rgb: "rgb(26, 214, 76, 255)",
                cmyk: "cmyk(88%, 0%, 64%, 16%, 255)",
                hsl: "hsl(136°, 78%, 47%, 255)",
                hsv: "hsv(136°, 88%, 84%, 255)",
                Lab: "Lab(75.1, -73.2, 66.1, 255)",
                hex: "#1AD64CFF"
            }
        }
    */
});
//Returns: 54 //Example of id returned

//To add a visibility event
picker.addEventListener(R9Picker.EVENT.VISIBILITY, (b) => {
    console.log(b);
    //Might print (when triggered): "false" //Example
});
//Returns: 54 //Example of id returned

//To add a canceled event
picker.addEventListener(R9Picker.EVENT.CANCELED, () => {
    console.log("banana");
    //Will print (when triggered): "banana"
});
//Returns: 55 //Example of id returned

removeEventListener()

Removes one or all event listener from the color picker.

Name	Type	Required	Description
eventOrId	Event's ID or R9Picker.EVENT constant	Yes	If a R9Picker.EVENT constant is passed all the corresponding events will be removed. If a event's ID is passed only the corresponding event will be removed.

Example


//To remove the event of ID 53
picker.removeEventListener(53);

//To remove all "input" events
picker.removeEventListener(R9Picker.EVENT.INPUT);

Extra

Related to extra features included in the color picker.

EyeDropper

The color picker includes the web feature EyeDropper, that allows the user to select any color from the device's screen.

If the feature is not supported by the user's browser, the EyeDropper button will be removed from the color picker. (See browser compatibility).

Click to copy

A color will be copied to the user's clipboard when:

- The user clicks on a letter from any input group. The color will be copied with the corresponding group string format, e.g. "hsv(47°, 87%, 59%)";

- The user clicks on the "Old", "Current" or sample color. The color will be copied in the hex format.

Log

v1.0.0Latest

Rainbow9

Rainbow9 Picker (R9Picker) has the Rainbow9 (R9) library built-in, and can be accessed using the corresponding static object (R9).

R9Picker version	R9 built-in version
v1.0.0	v1.1.0

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Credits

- The Rainbow9 Picker library uses the code from Barret Sonntag, released under the MIT License on CodePen. This code is used only to help changing the color of the icons in the color picker user interface (See UI color). Some modifications were made to the original code, which can be found at https://codepen.io/sosuke/pen/Pjoqqp.