This project might continue to get important security- and bug-related updates but its _feature set_ is frozen, and it's highly unlikely that it'll get new features or enhancements.
The reason behind this decision is the way this tool has been build (monolithic, the core is one single file, everything is in plain JS etc.) which makes it incredible hard to maintain, tests become impossible at this stage without a complete rewrite, and the fun is gone at such a level of cramped complexity.
Personally I recommend building these UI-Related "widgets" directly into the app with the framework you're using which takes more time but in return gives you full power of how it should work and look like. Frameworks such as (p)react, vue and svelte will make it a breeze to develop such things within a day.
Update
This project will be archived at the end of 2021!
After this there will be no more bug / security fixes or feature requests.
Themes
|Classic|Monolith|Nano|
|-------|--------|----|
|![Classic
Nano uses css-grid thus it won't work in older browsers.
Getting Started
Node
Note: The readme is always up-to-date with the latest commit. See Releases for installation instructions regarding to the latest version.
// Any combinations of top, left, bottom or right with one of these optional modifiers: start, middle, end
// Examples: top-start / right-end
// If clipping occurs, the color picker will automatically choose its position.
// Pickr uses https://github.com/Simonwep/nanopop as positioning-engine.
position:'bottom-middle',
// Enables the ability to change numbers in an input field with the scroll-wheel.
// To use it set the cursor on a position where a number is and scroll, use ctrl to make steps of five
adjustableNumbers:true,
// Show or hide specific components.
// By default only the palette (and the save button) is visible.
components:{
// Defines if the palette itself should be visible.
// Will be overwritten with true if preview, opacity or hue are true
palette:true,
preview:true,// Display comparison between previous state and new color
opacity:true,// Display opacity slider
hue:true,// Display hue slider
// show or hide components on the bottom interaction bar.
interaction:{
// Buttons, if you disable one but use the format in default: or setColor() - set the representation-type too!
hex:false,// Display 'input/output format as hex' button (hexadecimal representation of the rgba value)
rgba:false,// Display 'input/output format as rgba' button (red green blue and alpha)
hsla:false,// Display 'input/output format as hsla' button (hue saturation lightness and alpha)
hsva:false,// Display 'input/output format as hsva' button (hue saturation value and alpha)
cmyk:false,// Display 'input/output format as cmyk' button (cyan mangenta yellow key )
input:false,// Display input/output textbox which shows the selected color value.
// the format of the input is determined by defaultRepresentation,
// and can be changed by the user with the buttons set by hex, rgba, hsla, etc (above).
cancel:false,// Display Cancel Button, resets the color to the previous state
clear:false,// Display Clear Button; same as cancel, but keeps the window open
save:false,// Display Save Button,
},
},
// Translations, these are the default values.
i18n:{
// Strings visible in the UI
'ui:dialog':'color picker dialog',
'btn:toggle':'toggle color picker dialog',
'btn:swatch':'color swatch',
'btn:last-color':'use previous color',
'btn:save':'Save',
'btn:cancel':'Cancel',
'btn:clear':'Clear',
// Strings used for aria-labels
'aria:btn:save':'save and close',
'aria:btn:cancel':'cancel and close',
'aria:btn:clear':'clear and close',
'aria:input':'color input field',
'aria:palette':'color selection area',
'aria:hue':'hue selection slider',
'aria:opacity':'selection slider'
}
});
```
Selection through a Shadow-DOM
Example setup:
``` html
<div class="entry">
#shadow-root
<div class="innr">
<div class="another">
#shadow-root
<div class="pickr"></div>
</div>
</div>
</div>
```
To select the .pickr element you can use the custom >> shadow-dom-selector in el:
```js
el:'.entry >> .innr .another >> .pickr'
```
Every ShadowRoot of the query-result behind a >> gets used in the next query selection.
An alternative would be to provide the target-element itself as el.
The HSVaColor object
As default color representation is hsva (hue, saturation, value and alpha) used, but you can also convert it to other formats as listed below.
hsva.toHSVA() _- Converts the object to a hsva array._
hsva.toHSLA() _- Converts the object to a hsla array._
hsva.toRGBA() _- Converts the object to a rgba array._
hsva.toHEXA() _- Converts the object to a hexa-decimal array._
hsva.toCMYK() _- Converts the object to a cmyk array._
hsva.clone() _- Clones the color object._
The toString() is overridden, so you can get a color representation string.
```js
hsva.toRGBA();// Returns [r, g, b, a]
hsva.toRGBA().toString();// Returns rgba(r, g, b, a) with highest precision
hsva.toRGBA().toString(3);// Returns rgba(r, g, b, a), rounded to the third decimal
```
Methods
pickr.setHSVA(h:Number,s:Number,v:Number,a:Float, silent:Boolean) _- Set an color, returns true if the color has been accepted._
pickr.setColor(str: :String | null, silent:Boolean):Boolean _- Parses a string which represents a color (e.g. #fff, rgb(10, 156, 23)) or name e.g. 'magenta', returns true if the color has been accepted. null will clear the color._
If silent is true (Default is false), the button won't change the current color.
pickr.on(event:String, cb:Function):Pickr _- Appends an event listener to the given corresponding event-name (see section Events)._
pickr.off(event:String, cb:Function):Pickr _- Removes an event listener from the given corresponding event-name (see section Events)._
pickr.show():Pickr _- Shows the color-picker._
pickr.hide():Pickr _- Hides the color-picker._
pickr.disable():Pickr _- Disables pickr and adds the disabled class to the button._
pickr.enable():Pickr _- Enables pickr and removes the disabled class from the button._
pickr.isOpen():Pickr _- Returns true if the color picker is currently open._
pickr.getRoot():Object _- Returns the dom-tree of pickr as tree-structure._
pickr.getColor():HSVaColor _- Returns the current HSVaColor object._
pickr.getSelectedColor():HSVaColor _- Returns the currently applied color._
pickr.destroy() _- Destroys all functionality._
pickr.destroyAndRemove() _- Destroys all functionality and removes the pickr element including the button._
pickr.setColorRepresentation(type:String):Boolean _- Change the current color-representation. Valid options are HEX, RGBA, HSVA, HSLA and CMYK, returns false if type was invalid._
pickr.getColorRepresentation():String _- Returns the currently used color-representation (eg. HEXA, RGBA...)_
pickr.applyColor(silent:Boolean):Pickr _- Same as pressing the save button. If silent is true the onSave event won't be called._
pickr.addSwatch(color:String):Boolean _- Adds a color to the swatch palette. Returns true if the color has been successful added to the palette._
pickr.removeSwatch(index:Number):Boolean_- Removes a color from the swatch palette by its index, returns true if successful._
Static methods
Pickr
create(options:Object):Pickr _- Creates a new instance._
Pickr.utils
once(element:HTMLElement, event:String, fn:Function[, options :Object]) _- Attach an event handle which will be fired only once_
You can use useAsButton: true and pass a reference (or selector) of your input-element as el. Then you can update the input-element whenever a change was made. example.
I want to update options after mounting pickr, is that possible?
Unfortunately not. The core-code of this project is rather old (over 2 years), and I made it in my early js-days - the widget is not able to dynamically re-render itself in that way.
You have to destroy and re-initialize it.
Contributing
If you want to open a issue, create a Pull Request or simply want to know how you can run it on your local machine, please read the Contributing guide.
探客时代
