77 | Spectrum can be customized to show and hide different portions of the colorpicker. Try clicking some of the buttons below to see how it can change. 78 |
79 | 80 |94 | 95 | 96 | 97 |
98 |108 | This page has loaded the German localization. Here is a list of all spectrum localizations. Please help expand our localizations if you know a language that isn't represented! You can copy and paste one of the files, and update the text for 'cancel' and 'choose', then submit a pull request at: https://github.com/bgrins/spectrum. 109 |
110 |119 | NOTE: these palettes are also a work in progress. Ideally the site will eventually allow you to choose between a few options and download them. 120 |
121 | 122 |
123 | The newGmail palette below is an example of customizing the palette size and layout with CSS.
124 |
I wasn't satisfied with the solutions available for colorpicking. 53 | Many of them included a ton of images, were hard to skin or customize, or were very large plugins. 54 | Here are the goals I had when making a new one: 55 |
56 | 57 |Just include the needed CSS and JavaScript files, and you are ready to go!
60 |61 | <script src='spectrum.js'></script> 62 | <link rel='stylesheet' href='spectrum.css' /> 63 |64 |
We don't need no stinkin' images!
65 |Nobody wants to add a bunch of code into their project. Spectrum is contained in two files, and both are careful not to mess with your existing code.
66 | 67 |I wanted an option for the most basic use case, a polyfill for the input[type=color] HTML5 control. 69 | This mode needs to work without JavaScript enabled - and fallback to an input[type=text] like other HTML5 inputs. 70 |
71 |If you don't want this behavior to happen, but still want to use spectrum elsewhere on the page, you can set $.fn.spectrum.load = false; right after loading the script file.
Just because you don't have to change anything to get it to work, doesn't mean you can't! 76 | It is easy to skin and customize the plugin with CSS, and there are a wide range of modes and options to explore. 77 |
78 | 79 |Along with desktop browser support, I wanted a mobile colorpicker that was touch friendly, worked in iOS and Android, and used standards 81 | that maximize future mobile support. 82 |
83 | 84 |87 | Believe it or not, this colorpicker lives inside of Chrome, Firefox, and Safari devtools to make picking colors easier for web developers and designers. 88 |
89 | 90 |91 | When I started the project, I wrote about developer tools concept colorpicker implementation. After that, I was contacted on the devtools mailing list and got some initial feedback about the possibility of integrating it with devtools. Then I pulled the jQuery dependency out of a branch and I submitted a patch to the WebKit project. 92 |
93 | 94 |95 | From there, I opened a bug to start working on it Web Inspector. 50+ comments and 10 patches later, the case landed in WebKit. Here is the Firefox bug where it was added. 96 |
97 | 98 | 99 |If you want to get more into the functionality, just create a normal input and initialize it as a normal jQuery plugin. 103 | You can set a lot of options when initializing the colorpicker. 104 | See the 'Options' section below. 105 |
106 | 107 |108 | <input type='text' id="custom" /> 109 |110 | 111 |
112 | <script>
113 | $("#custom").spectrum({
114 | color: "#f00"
115 | });
116 | </script>
117 |
118 |
119 | Flat 125 | This means that it will always show up at full size, 126 | and be positioned as an inline-block element. 127 | Look to the left for a full sized flat picker. 128 |
129 | 130 |131 | <input type='text' id="flat" /> 132 | <br/> 133 | <input type='text' id="flat" /> 134 |135 |
136 | $("#flat").spectrum({
137 | flat: true,
138 | showInput: true
139 | });
140 | $("#flatClearable").spectrum({
141 | flat: true,
142 | showInput: true,
143 | allowEmpty:true
144 | });
145 |
146 |
147 | 156 | If you just want to provide a polyfill for the native color input, 157 | the easiest way is to create an input with the type of color. 158 | Once a user's browser supports a native color control, it will opt to use their native control instead. 159 |
160 |Unlike the other modes, your value must be a 6 character hex value starting with a '#'. Why? Because the spec says so, that's why. 161 |
162 | 163 |164 | <input type='color' name='color' /> 165 | <input type='color' name='color2' value='#3355cc' /> 166 |167 |
That's it! 176 | The field will degrade to a text input if the user does not have JavaScript enabled, 177 | so that they will still be able to manually enter a color. You don't need to add a single line of code. 178 |
179 | 180 | 185 | 186 |
188 | $("#picker").spectrum({
189 | color: tinycolor,
190 | flat: bool,
191 | showInput: bool,
192 | showInitial: bool,
193 | allowEmpty: bool,
194 | showAlpha: bool,
195 | disabled: bool,
196 | localStorageKey: string,
197 | showPalette: bool,
198 | showPaletteOnly: bool,
199 | togglePaletteOnly: bool,
200 | showSelectionPalette: bool,
201 | clickoutFiresChange: bool,
202 | cancelText: string,
203 | chooseText: string,
204 | togglePaletteMoreText: string,
205 | togglePaletteLessText: string,
206 | containerClassName: string,
207 | replacerClassName: string,
208 | preferredFormat: string,
209 | maxSelectionSize: int,
210 | palette: [[string]],
211 | selectionPalette: [string]
212 | });
213 |
214 | spectrum initializer, like $(element).spectrum({showAlpha: true }) or on the element's markup, like <input data-show-alpha="true" />.
216 |
222 | The initial color will be set with the color option.
223 | If you don't pass in a color, Spectrum will use the value attribute on the input.
224 |
226 | The color parsing is based on the TinyColor plugin. 227 | This should parse any color string you throw at it.
228 | 229 |232 | <input type='text' class='basic' value='red' /> 233 | <input type='text' class='basic' value='#0f0' /> 234 | <input type='text' class='basic' value='blue' /> 235 | <br /> 236 | <input type='text' class='override' /> 237 | <br /> 238 | <input type='text' class='startEmpty' value='' /> 239 |240 | 241 |
242 | <script>
243 | $(".basic").spectrum();
244 | $(".override").spectrum({
245 | color: "yellow"
246 | });
247 | (".startEmpty").spectrum({
248 | allowEmpty: true
249 | });
250 | </script>
251 |
252 | You can add an input to allow free form typing. The color parsing is very permissive in the allowed strings. See TinyColor for more details. 267 |
269 | $("#showInput").spectrum({
270 | showInput: true
271 | });
272 | $("#showInputWithClear").spectrum({
273 | showInput: true,
274 | allowEmpty:true
275 | });
276 |
277 | You can allow alpha transparency selection. Check out these examples:
288 |
290 | $("#showAlpha").spectrum({
291 | showAlpha: true
292 | });
293 |
294 | Spectrum can be automatically disabled if you pass in the disabled flag. Additionally, if the input that you initialize spectrum on is disabled, this will be the default value. Note: you cannot enable spectrum if the input is disabled (see below).
308 | $("#disabled").spectrum({
309 | disabled: true
310 | });
311 | $("input:disabled").spectrum({
312 |
313 | });
314 |
315 | Spectrum can show a palette below the colorpicker to make it convenient for users to choose from frequently or recently used colors. When the colorpicker is closed, the current color will be added to the palette if it isn't there already. Check it out here:
326 |
328 | $("#showPalette").spectrum({
329 | showPalette: true,
330 | palette: [
331 | ['black', 'white', 'blanchedalmond'],
332 | ['rgb(255, 128, 0);', 'hsv 100 70 50', 'lightyellow']
333 | ]
334 | });
335 |
336 | If you'd like, spectrum can show the palettes you specify, and nothing else.
348 |
351 | $("#showPaletteOnly").spectrum({
352 | showPaletteOnly: true,
353 | showPalette:true,
354 | color: 'blanchedalmond',
355 | palette: [
356 | ['black', 'white', 'blanchedalmond',
357 | 'rgb(255, 128, 0);', 'hsv 100 70 50'],
358 | ['red', 'yellow', 'green', 'blue', 'violet']
359 | ]
360 | });
361 |
362 | Spectrum can show a button to toggle the colorpicker next to the palette. This way, the user can choose from a limited number of colors in the palette, but still be able to pick a color that's not in the palette.
375 | The default value for togglePaletteOnly is FALSE. Set it to TRUE to enable the Toggle button.
376 | You can also change the text on the Toggle Button with the options togglePaletteMoreText (default is "more") and togglePaletteLessText (default is "less").
380 | $("#togglePaletteOnly").spectrum({
381 | showPaletteOnly: true,
382 | togglePaletteOnly: true,
383 | togglePaletteMoreText: 'more',
384 | togglePaletteLessText: 'less',
385 | color: 'blanchedalmond',
386 | palette: [
387 | ["#000","#444","#666","#999","#ccc","#eee","#f3f3f3","#fff"],
388 | ["#f00","#f90","#ff0","#0f0","#0ff","#00f","#90f","#f0f"],
389 | ["#f4cccc","#fce5cd","#fff2cc","#d9ead3","#d0e0e3","#cfe2f3","#d9d2e9","#ead1dc"],
390 | ["#ea9999","#f9cb9c","#ffe599","#b6d7a8","#a2c4c9","#9fc5e8","#b4a7d6","#d5a6bd"],
391 | ["#e06666","#f6b26b","#ffd966","#93c47d","#76a5af","#6fa8dc","#8e7cc3","#c27ba0"],
392 | ["#c00","#e69138","#f1c232","#6aa84f","#45818e","#3d85c6","#674ea7","#a64d79"],
393 | ["#900","#b45f06","#bf9000","#38761d","#134f5c","#0b5394","#351c75","#741b47"],
394 | ["#600","#783f04","#7f6000","#274e13","#0c343d","#073763","#20124d","#4c1130"]
395 | ]
396 | });
397 |
398 | Spectrum can keep track of what has been selected by the user with the showSelectionPalette option.
If the localStorageKey option is defined, the selection will be saved in the browser's localStorage object
414 | $("#showSelectionPalette").spectrum({
415 | showPalette: true,
416 | showSelectionPalette: true, // true by default
417 | palette: [ ]
418 | });
419 | $("#showSelectionPaletteStorage").spectrum({
420 | showPalette: true,
421 | showSelectionPalette: true,
422 | palette: [ ],
423 | localStorageKey: "spectrum.homepage", // Any Spectrum with the same string will share selection
424 | });
425 |
426 |
427 | The default values inside of the selection palette. Make sure that showSelectionPalette and showPalette are both enabled.
440 |If a localStorageKey is defined, then this value will be overwritten by it.
444 | $("#selectionPalette").spectrum({
445 | showPalette: true,
446 | palette: [ ],
447 | showSelectionPalette: true, // true by default
448 | selectionPalette: ["red", "green", "blue"]
449 | });
450 |
451 |
452 | This is how many elements are allowed in the selectionPallete at once.
462 |Elements will be removed from the palette in first in - first out order if this limit is reached.
463 |
466 | $("#maxSelectionSize").spectrum({
467 | showPalette: true,
468 | palette: [ ],
469 | showSelectionPalette: true, // true by default
470 | selectionPalette: ["red", "green", "blue"],
471 | maxSelectionSize: 2
472 | });
473 |
474 |
475 | You can have the colorpicker automatically hide after a palette color is selected.
485 |
488 | $("#hideAfterPaletteSelect").spectrum({
489 | showPaletteOnly: true,
490 | showPalette:true,
491 | hideAfterPaletteSelect:true,
492 | color: 'blanchedalmond',
493 | palette: [
494 | ['black', 'white', 'blanchedalmond',
495 | 'rgb(255, 128, 0);', 'hsv 100 70 50'],
496 | ['red', 'yellow', 'green', 'blue', 'violet']
497 | ]
498 | });
499 |
500 |
513 | When clicking outside of the colorpicker, you can force it to fire a change event rather than having it revert the change. This is true by default.
514 |
518 | $("#clickoutFiresChange").spectrum({
519 | clickoutFiresChange: true
520 | });
521 | $("#clickoutDoesntChange").spectrum({
522 | clickoutFiresChange: false
523 | });
524 |
525 |
526 | 536 | Spectrum can show the color that was initially set when opening. 537 | This provides an easy way to click back to what was set when opened. 538 |
539 |
542 | $("#showInitial").spectrum({
543 | showInitial: true
544 | });
545 |
546 |
547 | If you specify both the showInput and showInitial options, the CSS keeps things in order by wrapping the buttons to the bottom row, and shrinking the input. Note: this is all customizable via CSS.
558 | $("#showInputAndInitial").spectrum({
559 | showInitial: true,
560 | showInput: true
561 | });
562 |
563 |
564 | If you specify both the showInput, showInitial, and allowEmpty options, the CSS keeps things in order by wrapping the buttons to the bottom row, and shrinking the input. Note: this is all customizable via CSS.
574 | $("#showInputInitialClear").spectrum({
575 | allowEmpty:true,
576 | showInitial: true,
577 | showInput: true
578 | });
579 |
580 |
581 | You can set the button's text using cancelText and chooseText properties.
592 | $("#buttonText").spectrum({
593 | allowEmpty:true,
594 | chooseText: "Alright",
595 | cancelText: "No way"
596 | });
597 |
598 |
599 |
608 | You can show or hide the buttons using the showButtons property.
609 | If there are no buttons, the behavior will be to fire the `change` event (and update the original input) when the picker is closed.
610 |
614 | $("#hideButtons").spectrum({
615 | showButtons: false
616 | });
617 |
618 |
619 |
628 | You can add an additional class name to the just the container element using the containerClassName property.
629 |
633 | $("#containerClassName").spectrum({
634 | containerClassName: 'awesome'
635 | });
636 |
637 |
638 | .awesome {
639 | background: purple;
640 | }
641 |
642 |
647 |
648 |
657 | You can add an additional class name to just the replacer element using the replacerClassName property.
658 |
662 | $("#replacerClassName").spectrum({
663 | replacerClassName: 'awesome'
664 | });
665 |
666 |
667 | .awesome {
668 | background: purple;
669 | }
670 |
671 |
676 |
677 | You can set the format that is displayed in the text box.
686 |This will also change the format that is displayed in the titles from the palette swatches.
687 |
690 | $("#preferredHex").spectrum({
691 | preferredFormat: "hex",
692 | showInput: true,
693 | showPalette: true,
694 | palette: [["red", "rgba(0, 255, 0, .5)", "rgb(0, 0, 255)"]]
695 | });
696 | $("#preferredHex3").spectrum({
697 | preferredFormat: "hex3",
698 | showInput: true,
699 | showPalette: true,
700 | palette: [["red", "rgba(0, 255, 0, .5)", "rgb(0, 0, 255)"]]
701 | });
702 | $("#preferredHsl").spectrum({
703 | preferredFormat: "hsl",
704 | showInput: true,
705 | showPalette: true,
706 | palette: [["red", "rgba(0, 255, 0, .5)", "rgb(0, 0, 255)"]]
707 | });
708 | $("#preferredRgb").spectrum({
709 | preferredFormat: "rgb",
710 | showInput: true,
711 | showPalette: true,
712 | palette: [["red", "rgba(0, 255, 0, .5)", "rgb(0, 0, 255)"]]
713 | });
714 | $("#preferredName").spectrum({
715 | preferredFormat: "name",
716 | showInput: true,
717 | showPalette: true,
718 | palette: [["red", "rgba(0, 255, 0, .5)", "rgb(0, 0, 255)"]]
719 | });
720 | $("#preferredNone").spectrum({
721 | showInput: true,
722 | showPalette: true,
723 | palette: [["red", "rgba(0, 255, 0, .5)", "rgb(0, 0, 255)"]]
724 | });
725 |
726 | You can choose which element the colorpicker container is appended to (default is "body"). This can be any valid object taken into the jQuery appendTo function.
Changing this can help resolve issues with opening the colorpicker in a modal dialog or fixed position container, for instance.
747 |
753 | // Events can be bound in the intialization process as options:
754 | $("#picker").spectrum({
755 | move: function(tinycolor) { },
756 | show: function(tinycolor) { },
757 | hide: function(tinycolor) { },
758 | beforeShow: function(tinycolor) { },
759 | });
760 |
761 | // Alternatively, they can be added as an event listener:
762 | $("#picker").on('move.spectrum', function(e, tinycolor) { });
763 | $("#picker").on('show.spectrum', function(e, tinycolor) { });
764 | $("#picker").on('hide.spectrum', function(e, tinycolor) { });
765 | $("#picker").on('beforeShow.spectrum', function(e, tinycolor) { });
766 |
767 |
768 | Called as the original input changes. Only happens when the input is closed or the 'Choose' button is clicked.
772 |
775 | change: function(color) {
776 | color.toHexString(); // #ff0000
777 | }
778 |
779 |
780 | Called as the user moves around within the colorpicker
791 |
794 | move: function(color) {
795 | color.toHexString(); // #ff0000
796 | }
797 |
798 |
799 | 811 | Called after the colorpicker is hidden. 812 | This happens when clicking outside of the picker while it is open. 813 | Note, when any colorpicker on the page is shown it will hide any that are already open. 814 | This event is ignored on a flat colorpicker. 815 |
816 |
819 | hide: function(color) {
820 | color.toHexString(); // #ff0000
821 | }
822 |
823 |
824 | 835 | Called after the colorpicker is opened. 836 | This is ignored on a flat colorpicker. 837 | Note, when any colorpicker on the page is shown it will hide any that are already open. 838 |
839 |
842 | show: function(color) {
843 | color.toHexString(); // #ff0000
844 | }
845 |
846 |
847 | 858 | You can prevent the colorpicker from showing up if you return false in the beforeShow event. 859 | This event is ignored on a flat colorpicker. 860 |
861 |
864 | beforeShow: function(color) {
865 | return false; // Will never show up
866 | }
867 |
868 |
869 | 879 | Called at the beginning of a drag event on either 880 | hue slider, alpha slider, or main color picker areas 881 |
882 |
885 | $(element).on("dragstart.spectrum", function(e, color) {
886 | color.toHexString(); // #ff0000
887 | });
888 |
889 |
890 | 901 | Called at the end of a drag event on either 902 | hue slider, alpha slider, or main color picker areas 903 |
904 |
907 | $(element).on("dragstop.spectrum", function(e, color) {
908 | color.toHexString(); // #ff0000
909 | });
910 |
911 |
912 |
921 | $("#picker").spectrum("show");
922 | $("#picker").spectrum("hide");
923 | $("#picker").spectrum("toggle");
924 | $("#picker").spectrum("get");
925 | $("#picker").spectrum("set", colorString);
926 | $("#picker").spectrum("container");
927 | $("#picker").spectrum("reflow");
928 | $("#picker").spectrum("destroy");
929 | $("#picker").spectrum("enable");
930 | $("#picker").spectrum("disable");
931 | $("#picker").spectrum("option", optionName);
932 | $("#picker").spectrum("option", optionName, newOptionValue);
933 |
934 |
935 | 940 | Shows the colorpicker. 941 |
942 |950 | Hides the colorpicker. 951 |
952 |960 | Toggles the colorpicker. 961 |
962 |
963 | Warning: If you are calling toggle from a click handler, make sure you return false to prevent the colorpicker from immediately hiding after it is toggled.
964 |
968 | $("#btn-toggle").click(function() {
969 | $("#toggle").spectrum("toggle");
970 | return false;
971 | });
972 |
973 |
974 | 985 | Gets the current value from the colorpicker. 986 |
987 |995 | Setting the colorpicker programmatically will update the original input. 996 |
997 |
998 | Note: this will not fire the change event,
999 | to prevent infinite loops from calling set from within change.
1000 |
1004 | <input type='text' value='blanchedalmond' name='triggerSet' id='triggerSet' />
1005 | <input type='text' placeholder='Enter A Color' id='enterAColor' />
1006 | <button id='btnEnterAColor'>Trigger Set</button>
1007 |
1008 | <script>
1009 | $("#triggerSet").spectrum();
1010 |
1011 | // Show the original input to demonstrate the value changing when calling `set`
1012 | $("#triggerSet").show();
1013 |
1014 | $("#btnEnterAColor").click(function() {
1015 | $("#triggerSet").spectrum("set", $("#enterAColor").val());
1016 | });
1017 | </script>
1018 |
1019 |
1020 | 1031 | Retrieves the container element of the colorpicker, in case you want to manaully position it or do other things. 1032 |
1033 |1041 | Resets the positioning of the container element. This could be used was hidden when initialized, or if the colorpicker is inside of a moving area. 1042 |
1043 |1051 | Removes the colorpicker functionality and restores the element to its original state. 1052 |
1053 |1061 | Allows selection of the colorpicker component. If it is already enabled, this method does nothing. 1062 |
1063 |1064 | Additionally, this will cause the original (now hidden) input to be set as disabled. 1065 |
1066 |
1074 | Disables selection of the colorpicker component. Adds the sp-disabled class onto the replacer element. If it is already disabled, this method does nothing.
1075 |
1077 | Additionally, this will remove the disabled property on the original (now hidden).
1078 |
1087 | Calling option with an option name will return the current value of that option. So, for example:
1088 |
1090 | $("input").spectrum({
1091 | showInput: true
1092 | });
1093 |
1094 | $("input").spectrum("option", "showInput"); // true
1095 |
1096 |
1097 | Calling option with an option name and an option value will set the option to the new value.
1098 |
1100 | $("input").spectrum({
1101 | showInput: true
1102 | });
1103 |
1104 | $("input").spectrum("option", "showInput", false);
1105 | $("input").spectrum("option", "showInput"); // false
1106 |
1107 | Since it is all built with HTML/CSS, you can skin it easily. There are two parts to the spectrum.css file, the core rules (at the top of the file), and the themable rules (at the bottom). Feel free to tweak these rules to make it look how you want.
1114 | 1115 |
1117 | You can use any element you would like to trigger the colorpicker: Click me to open a colorpicker, though it is strongly recommended to stick with <input> tags.
1118 |
I wanted this to work in the latest and greatest browsers, but also target backwords compatibility and mobile support. 1124 | Here are the currently supported browers: 1125 |
1136 | IE Support is provided using 1137 | proprietary filters. 1138 | Other browsers use CSS gradients. 1139 |
1140 | 1141 | 1142 |Spectrum will use the color passed in to initialize. If there is no color passed in,
1144 | it will try to parse a color based on the value of the input. The color parsing is based on the TinyColor plugin, and accepts many forms of input:
1146 | red 1147 | #fff 1148 | fff 1149 | #ffffff 1150 | ffffff 1151 | rgb(255, 0, 0) 1152 | rgb 255 0 0 1153 | hsl(0, 100, 50) 1154 | hsl(0, 100%, 50%) 1155 | hsl 0 100 50 1156 | hsl 0 100% 50% 1157 | hsv(0, 100%, 100%) 1158 | hsv(0, 100, 100) 1159 | hsv 0 100% 100% 1160 | hsv 0 100 100 1161 |1162 |
It also provides the following forms of output:
1163 |
1164 | var t = $("#element").spectrum("get");
1165 | t.toHex() // "ff0000"
1166 | t.toHexString() // "#ff0000"
1167 | t.toRgb() // {"r":255,"g":0,"b":0}
1168 | t.toRgbString() // "rgb(255, 0, 0)"
1169 | t.toHsv() // {"h":0,"s":1,"v":1}
1170 | t.toHsvString() // "hsv(0, 100%, 100%)"
1171 | t.toHsl() // {"h":0,"s":1,"l":0.5}
1172 | t.toHslString() // "hsl(0, 100%, 50%)"
1173 | t.toName() // "red"
1174 |
1175 |
1176 |
1177 |
1194 |
1195 | This is the default theme that you know and love.
43 | 44 |Similar to sp-light, only ... darker
52 | 53 |62 | You can change most any property on spectrum using CSS. Anything from borders and colors, to the size of the draggable areas, to the layout of the colorpicker can be changed with plain CSS. 63 |
64 |
66 | Please prefix all of your rules with .theme-name. The exception is for changes to .sp-container and .sp-replacer, which will have your theme name applied.
67 |
69 | See a basic scaffold for a super simple theme. See sp-dark.css for a slightly more advanced example. 70 |
71 |
72 | .theme-name.sp-container {
73 |
74 | }
75 | .theme-name.sp-replacer {
76 |
77 | }
78 | .theme-name .sp-preview {
79 |
80 | }
81 |
82 | 84 | If you have made some customizations that you would like to share, please open a pull request with the theme file inside of this themes/ directory in the project. Or open an issue with a link to the theme. 85 |
86 |