JointJS+ ColorPalette

You may see the name Rappid in our documentation, code and other materials. Rappid has been replaced by a new brand, JointJS+. This change has no effect on functionality. To avoid confusion, please consider Rappid and JointJS+ as synonyms. Read more here.

ui.ColorPalette

ui.ColorPalette is a UI widget for displaying dropdowns with color palette.

Installation

Include joint.ui.colorPalette.js and joint.ui.colorPalette.css files to your HTML:

<link rel="stylesheet" type="text/css" href="joint.ui.colorPalette.css">
<script src="joint.ui.colorPalette.js"></script>

Usage

Create an object of ui.ColorPalette type, render it with the render() method and append the generated HTML element anywhere in your DOM:

var colorPalette = new joint.ui.ColorPalette({
    options: [
	{ content: '#000000' },
	{ content: '#FFFFFF' },
	{ content: 'transparent', icon: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGoAAABrCAYAAACffRcyAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAABPxJREFUeNrsnc9rU1kUx+/LS2LTBtI4VMiqjYjiQgQ3IoIUuhvGUmYzUBgV8SdWLS7sooLgxm0XgjKg0P+gMDC7ggjDzGwGOt1psS2WBptioiYVmrbxnviiSc17eaPvvdzz7vcLlyTk5vVyPtzzzv3mtDWq1arYrVwuNyAfxuUYkaNfQEFoWY4ZOaYymczS7jeNRlASUC9NlOMs4tZRTdNGkcCKX4GyID2V4yjipITm5Bisw4oAkrIiFk8tNp9AWekOkNSENVVLfaurq1Q4LCImSisbtao7R5mmWTQMYxPx8l6yRohvb2/3tpk2HrVKcFtA6XT6WSwWKyOk/qlSqfQUCoVTDsBGIk7nJEAKRhRjirXDlP6I024CpGBhUczt3rcFhXtS8HKKeQTh4aHot35Q3vyObW1tpdvNSyQSi8lk8iWu1yFQtGg59rWbJyuZNVzv+4XUx0QABVCa68+/0mJi8oj4/Y99Xlwuioj6BOn8lSHx4UOs9vr0j2vYUYrJ/G++6zOkRKIihn9aQepTzV14viB6Lo5lP0N68mhWnDxRACjFIP1w9YYwNjZMryEBlNeQSmVR7e7e9hoSib44rLasMqLRtb6+vlm7D5ZKpf3ycNfj4qCY2tnZ2dM2t5tmSY4NbtejexKlO9pJBOndbw/ym4cPtd0ArRyMfD4/ZHeo/uaqz61N4vTDGxWPx9dSqdQ8q+tRdXfhGhUOtXRnPH44u3nwwDE/HAykPi9KcB/uSQDFEBJAMYEEUEwgAdT3OA4BQgIoBRwHgGLiOAAUE8fBrXzvmaATPR0W3TgEdPhU5Xo1x+Hy9WbHQR5m5QnZk/XJOa8DAeW2h0A3x8Ht+pD6GJfgAMUcEkDZQSLdmfhbFUgAZQfp9q1/xK+jKyotUXtQTY5DHdLYlZeqrVNrUE2Og8KQtAbV5DgoDklbUI2OAwdIJO16Jhp7HOh1eXLizcbPw1tBrw89E24dB2snSUjZTqwPPRP/pwRXPN3pB4o5JD1AhQBS+EGFBFKoQXFxHLQGxclx0BYUN8dBS1CR9yWRuneflePgVqHpmTCKb83kxWvZyOJSV4PjkJUn0KwK62txgNawZyKfj4vRc0Pi1UpXpx0H9EzYRzAuRn4hSL1hS3fhAaUJJN6gNILEF5RmkFiCoupON0jsQNE5KXnmQlY3SKxAEaS9V2+K+jlJJ0hsQNUhxV4sCB0h1VK+6j0TNcdBprtdjkPgPQ7omQiZ46Bfz4SGJTg/UIDEABQgMQAFSOqD0tVxYAVKZ8eBDSjdHQcWoOA4uFfHeia49Tjo2TMRYschPD0TKMEZgAIkBqAAiQEoQFIfFBwHBqDgODAABceBASg4Dj7cQrzumQhrj0O4eibgODDomUAJzuAeBUhMQF0aOw5IHECVy3FA8lfe/HvXu5P/1h4V+husANVKAMTXmYAACqnPD9EJ3M3hzm0PgW7XCwyU29/6wPWQ+nCPghQAVa1W4whPsHKKuS0oeUPsrVQqPQhfMKJYU8ydQC3bvVkoFE4BVjCQKNYOU5ap6puR46bdrlpfXx82TbNoGMYmQupPunPaSZZm6BveAflkESFTWtlIJpNZkk+mEQtlNU2M6sXEuBxziIlymrPYfKr6JLGifBgELOUgDVpsvpTnDbCQBhVId42QSIasOr6alcvlBqwtNyJHP+IWiJatCnzKqhua1BIUpJ4+CjAAVnYzLhKE5pcAAAAASUVORK5CYII=' },
	{ content: '#B3B3B3' },
	{ content: '#808080' },
	{ content: '#4D4D4D' },
	{ content: '#E6E6E6' },
	{ content: '#FFC7C9' },
	{ content: '#FFA0A4' },
	{ content: '#E3686D' },
	{ content: '#D71920' },
	{ content: '#FFE3D1' },
	{ content: '#FFCBA8' },
	{ content: '#FFAB73' },
	{ content: '#F58235' }
    ]
});
document.body.appendChild(colorPalette.render().el);

Configuration

The following table lists options that you can pass to the ui.ColorPalette constructor function. You might notice that many of the options are similar to the ui.SelectBox widget. This is because the ui.ColorPalette inherits from this widget.

width The width of the color palette in pixels.
options An array of items. Each item is an object with the following properties:
content The color in hex or other color formats (rgb, rgba).
icon A path to an image (note that it can also be an image embedded via the Data URI Scheme). The icon can be handy for representing the transparent color.
selected true if the item should be selected by default. If non of the items are selected, the first item is selected by default.
selected The index of the item which should be selected by default. If this value is undefined (which it is by default), the ui.ColorPalette widget looks up the selected item from the options array (by using the selected boolean property). If nothing is selected, the first item in the options array is selected by default.
keyboardNavigation true (the default) if you want the ui.ColorPalette to provide a keyboard navigation (up/down/left/right/enter/escape keys are supported).
selectBoxOptionsClass When the color palette is opened, the ui.ColorPalette generates an HTML container that contains all the items. This container is then appended to the document body (or target if provided). Sometimes, you want to provide custom styling to this color palette container. selectBoxOptionsClass gives you a chance to define a CSS class that will be set on this container so that you can style it in your CSS.
target ui.ColorPalette generates an HTML container that contains all the color palette items. This container is by default appended to the document body. In some situations (e.g. if you want the color palette to scroll with some other container), you want to append this container to a different DOM element. The target option is exactly for that. It accepts an HTML element that will be used as a container for the generated color palette items.
placeholder In some cases, you want to deselect the color palette and show a placeholder in place of the selected item. This is when you don't want any of the items to be selected. In this case, set the selected index to -1 and the placeholder to any HTML you want to display in the selected item window. This placeholder has the selected-box-placeholder CSS class that you can use for further styling.

API

render() Render the color palette. Note that once you render the color palette, you can use the el property that points to the container HTML element and append it anywhere in the DOM (e.g. $(document.body).append(colorPalette.el)).
getSelection() Get the current selection. The selection points to one of the items from the options array.
getSelectionValue() Get the current selection value (the color).
getSelectionIndex() Get the index in the options array of the item that is currently selected.
select(index, opt) Select an item. index is the index to the options array. opt is optional and can be an arbitrary object that will be passed to the option:select event handler.
selectByValue(color) Select an item by color.
isOpen() Returns true if the color palette is currently opened. false otherwise.
toggle() Programmatically toggle the color palette.
open() Programmatically open the color palette.
close() Programmatically close the color palette.
remove() Remove the color palette from the DOM.
on(event, handler [, context]) Register a handler function that will be called whenever event is triggered. The optional context is an object that will be the context of the handler function (the this).

Events

The ui.ColorPalette object triggers various events that you can react on. Events can be handled by using the on() method (see above).

option:hover Triggered when the user hovers over one of the color items. The handler is passed the option object and the index of the option in the options array.
option:select Triggered when the user selects an item. The handler is passed the option object and the index of the option in the options array. If you selected the item with the select(index, opt) method, the third argument to the event handler will be your opt object.
option:mouseout Triggered when the user leaves an item with mouse cursor. The handler is passed an event object as the only argument.
close Triggered when the color palette gets closed.