Flat, Simple, Hackable Color-Picker.
Features
- Simple usage
- No jQuery
- No dependencies
- Multiple color representations
- Color comparison
- Opacity control
- Detail adjustments via. mouse-wheel
- Responsive and auto-positioning
- Supports touch devices
- Swatches for quick-selection
- Shadow-dom support
Setup
â ď¸ Attention: The readme is always up-to-date with the latest commit. See Releases for installation instructions regarding to the latest version.
Node
Install via npm:
$ npm install @simonwep/pickr
Install via yarn:
$ yarn add @simonwep/pickr
Include code and style:
import '/node_modules/@simonwep/pickr/dist/pickr.min.css';
import Pickr from '/node_modules/@simonwep/pickr/dist/pickr.min';
import Pickr from '/node_modules/@simonwep/pickr/dist/pickr.es5.min';
Browser
jsdelivr:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@simonwep/pickr/dist/pickr.min.css"/>
<script src="https://cdn.jsdelivr.net/npm/@simonwep/pickr/dist/pickr.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@simonwep/pickr/dist/pickr.es5.min.js"></script>
Be sure to load the pickr.min.js
(or the es5 version) after pickr.min.css
. Moreover the script
tag doesn't work with the defer
attribute.
Usage
const pickr = Pickr.create({
el: '.color-picker',
components: {
preview: true,
opacity: true,
hue: true,
interaction: {
hex: true,
rgba: true,
hsla: true,
hsva: true,
cmyk: true,
input: true,
clear: true,
save: true
}
}
});
Events
Since version 0.4.x
Pickr is event-driven. Use the on(event, cb)
and off(event, cb)
functions to bind / unbind eventlistener.
Event | Description | Arguments |
---|
init | Initialization done - pickr can be used | PickrInstance |
save | User clicked the save / clear button | HSVaColorObject | null, PickrInstance |
change | Color has changed (but not saved). Also fired on swatchselect | HSVaColorObject, PickrInstance |
swatchselect | User clicked one of the swatches | HSVaColorObject, PickrInstance |
Example:
pickr.on('init', (...args) => {
console.log('init', args);
}).on('save', (...args) => {
console.log('save', args);
}).on('change', (...args) => {
console.log('change', args);
}).on('swatchselect', (...args) => {
console.log('swatchselect', args);
});
Options
const pickr = new Pickr({
el: '.color-picker',
appClass: 'custom-class',
useAsButton: false,
inline: false,
disabled: false,
comparison: true,
default: 'fff',
swatches: ['#F44336', '#E91E63', '#9C27B0', '#673AB7'],
defaultRepresentation: 'HEX',
showAlways: false,
closeWithKey: 'Escape',
position: 'bottom-middle',
adjustableNumbers: true,
components: {
palette: true,
preview: true,
opacity: true,
hue: true,
interaction: {
hex: true,
rgba: true,
hsla: true,
hsva: true,
cmyk: true,
input: true,
clear: true,
save: true
},
},
strings: {
save: 'Save',
clear: 'Clear'
}
});
Selection through a Shadow-DOM
Example setup:
<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
:
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 cymk array.
- hsva.clone() - Clones the color object.
The toString()
is overridden so you can get a color representaion string.
hsva.toRGBA();
hsva.toRGBA().toString();
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(representation
:String
, 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
) - Appends an eventlistener to the given corresponding event-name (see section Events), returns the pickr instance so it can be chained. - pickr.off(event
:String
, cb:Function
) - Removes an eventlistener from the given corresponding event-name (see section Events), returns the pickr instance so it can be chained. - pickr.show() - Shows the color-picker, returns instance.
- pickr.hide() - Hides the color-picker, returns instance.
- pickr.disable() - Disables pickr and adds the
disabled
class to the button, returns instance. - pickr.enable() - Enables pickr and removes the
disabled
class from the button, returns instance. - pickr.isOpen() - Returns true if the color picker is currently open.
- pickr.getRoot()
:HTMLElement
- Returns the root DOM-Element of the color-picker. - pickr.getColor()
:HSVaColor
- Returns the current HSVaColor object. - pickr.destroy()
:HSVaColor
- Destroy's all functionality. - pickr.destroyAndRemove()
:HSVaColor
- Destroy's 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.applyColor(silent
:Boolean
) - 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
) - Removes a color from the swatch palette by its index.
Static methods
Pickr
- 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 - on(elements
:HTMLElement(s)
, events:String(s)
, fn:Function
[, options :Object
]) - Attach an event handler function. - off(elements
:HTMLElement(s)
, event:String(s)
, fn:Function
[, options :Object
]) - Remove an event handler. - createElementFromString(html
:String
):HTMLElement
- Creates an new HTML Element out of this string. - eventPath(evt
:Event
):[HTMLElement]
- A polyfill for the event-path event propery. - removeAttribute(el
:HTMLElement
, name:String
) - Removes an attribute from a HTMLElement and returns the value. - createFromTemplate(str
:String
) - See inline doumentation. - adjustableInputNumbers(el
:InputElement
, negative:Boolean
) - Creates the possibility to change the numbers in an inputfield via mouse scrolling. - padStart(string
:String
, maxLength:Number
, fillString = ' ') - String.prototype.padStart polyfill.
Use this utils carefully, it's not for sure that they will stay forever!
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.