Color Picker

<pc-color-picker>

1.0.0-alpha.2

experimental

Colour pickers allow the user to pick a colour.

<pc-color-picker label="Pick a colour"></pc-color-picker>

Code

Edit

This component works well with standard <form> elements. Please refer to the form controls page to learn more about form submission and client‐side validation.

Demos#

Initial value#

Use the value attribute to set an initial value for the colour picker.

<pc-color-picker value="#493ccf" label="Pick a colour"></pc-color-picker>

Code

Edit

Opacity#

Use the opacity attribute to enable the opacity slider.

<pc-color-picker value="#493ccf80" label="Pick a colour" opacity></pc-color-picker>

Code

Edit

Formats#

Use the format attribute to set the colour picker’s format. Valid options include hex, rgb, hsl and hsv. Note that the colour picker’s input will accept any parsable format (including CSS colour names) regardless of this option.

To prevent users from toggling the format themselves, add the no-format-toggle attribute.

<div class="pc-grid" style="--min-column-size: 15ch">
    <pc-color-picker
        format="hex"
        value="#493ccf"
        label="Pick a hex colour"
    ></pc-color-picker>
    <pc-color-picker
        format="rgb"
        value="#c32061"
        label="Pick an RGB colour"
    ></pc-color-picker>
    <pc-color-picker
        format="hsl"
        value="#256bb1"
        label="Pick an HSL colour"
    ></pc-color-picker>
    <pc-color-picker
        format="hsv"
        value="#b12525"
        label="Pick an HSV colour"
    ></pc-color-picker>
</div>

Code

Edit

Swatches#

Use the swatches attribute to add convenient presets to the colour picker. Any format the colour picker can parse is acceptable (including CSS colour names), but each value must be separated by a semicolon (;). Alternatively, you can pass an array of colour values to this property using JavaScript.

<pc-color-picker
    label="Pick a colour"
    swatches="
        #d92626; #d97026; #cf8f0f; #1fa84e;
        #1696b7; #2680d9; #554aea; #9838ef;
        #e12e7c; #181e2b; #1e2534; #262f40;
        #435069; #7987a2; #c9cdd7; #eaebee
    "
></pc-color-picker>

Code

Edit

Size#

Use the size attribute to change the colour picker’s size.

<div class="pc-align-items-baseline pc-gap-l">
    <pc-color-picker size="small" label="Pick a colour"></pc-color-picker>
    <pc-color-picker size="medium" label="Pick a colour"></pc-color-picker>
    <pc-color-picker size="large" label="Pick a colour"></pc-color-picker>
</div>

Code

Edit

Disabled#

Use the disabled attribute to disable the colour picker.

<pc-color-picker label="Pick a colour" disabled></pc-color-picker>

Code

Edit

Inline#

The colour picker can be rendered inline instead of in a popup using the inline attribute.

<pc-color-picker label="Pick a colour" inline></pc-color-picker>

Code

Edit

Properties#

Name	Description	Default
`value`	The current value of the colour picker. The value’s format will vary based on the `format` attribute. To get the value in a specific format, use the `getFormattedValue()` method. The value is submitted as a name/value pair with form data. Type: `string`	`""`
`defaultValue`	The default value of the colour picker. Primarily used for resetting the colour picker. Type: `string`	`""`
`label`	The colour picker’s label. If you need to display HTML, use the `label` slot instead. Type: `string`	`""`
`hint`	The colour picker’s hint. If you need to display HTML, use the `hint` slot instead. Type: `string`	`""`
`format`	The format to use. The colour picker will accept user input in any format (including CSS colour names) and convert it to the desired format. Type: `"hex" \| "rgb" \| "hsl" \| "hsv"`	`"hex"`
`inline`	Renders the color picker inline rather than in a dropdown. Type: `boolean`	`false`
`size`	Determines the size of the colour picker’s trigger. This has no effect on inline colour pickers. Type: `"small" \| "medium" \| "large"`	`"medium"`
`noFormatToggle` `no-format-toggle`	Removes the button that lets users toggle between formats. Type: `boolean`	`false`
`name`	The name of the colour picker, submitted as a name/value pair with form data. Type: `string`	`""`
`disabled`	Disables the colour picker. Type: `boolean`	`false`
`open`	Indicates whether or not the popup is open. You can toggle this attribute to show and hide the popup, or you can use the `show()` and `hide()` methods and this attribute will reflect the popup’s open state. Type: `boolean`	`false`
`opacity`	Shows the opacity slider. Type: `boolean`	`false`
`uppercase`	By default, values are lowercase. With this attribute, values will be uppercase instead. Type: `boolean`	`false`
`swatches`	One or more predefined colour swatches to display as presets in the colour picker. Can include any format the colour picker can parse, including hex, rgb, hsl, hsv and CSS colour names. Each colour must be separated by a semicolon (`;`). Alternatively, you can pass an array of colour values to this property using JavaScript. Type: `string \| string[]`	`""`
`form`	By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you to place the form control outside of a form and associate it with the form that has this `id`. The form must be in the same document or shadow root for this to work. Type: `string`	`""`
`required`	Indicates if the colour picker must be filled in or not. Type: `boolean`	`false`
`validity`	Gets the validity state object.	‐
`validationMessage`	Gets the validation message.	‐
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	‐

Learn more about attributes and properties.

Slots#

Name	Description
`label`	The colour picker’s label. Alternatively, you can use the `label` attribute.
`hint`	The colour picker’s hint. Alternatively, you can use the `hint` attribute.

Learn more about using slots.

Methods#

Name	Description	Arguments
`focus()`	Focuses the colour picker.	`options: FocusOptions`
`blur()`	Unfocuses the colour picker (i.e., blurs it).	‐
`getFormattedValue()`	Returns the current value as a string in the specified format.	`format: "hex" \| "hexa" \| "rgb" \| "rgba" \| "hsl" \| "hsla" \| "hsv" \| "hsva"`
`show()`	Shows the colour picker popup.	‐
`hide()`	Hides the colour picker popup.	‐
`checkValidity()`	Checks for validity but does not show a validation message. Returns `true` when valid and `false` when invalid.	‐
`getForm()`	Gets the associated form, if one exists.	‐
`reportValidity()`	Checks for validity and shows the browser’s validation message if the control is invalid.	‐
`setCustomValidity()`	Sets a custom validation message. Pass an empty string to restore validity.	`message: string`

Learn more about methods.

Events#

Name	Description	Event detail
`pc-change`	Emitted when the colour picker’s value changes.	‐
`pc-input`	Emitted when the colour picker receives input.	‐
`pc-focus`	Emitted when the colour picker receives focus.	‐
`pc-blur`	Emitted when the colour picker loses focus (i.e., is blurred).	‐
`pc-invalid`	Emitted when the form control has been checked for validity and its constraints aren’t satisfied.	‐

Learn more about events.

Custom properties#

Name	Description	Default
`--grid-width`	The width of the colour grid.	`17em`
`--grid-height`	The height of the colour grid.	`12em`
`--grid-handle-size`	The size of the colour grid’s handle.	`1.25em`
`--slider-height`	The height of the hue and alpha sliders.	`1em`
`--slider-thumb-size`	The size of both slider thumbs.	`calc(var(--slider-height) + 0.25em)`
`--swatch-size`	The size of each predefined colour swatch.	`1.5em`

Learn more about customising custom properties.

Parts#

Name	Description
`base`	The component’s base wrapper.
`popup`	The colour picker’s popup popup.
`trigger`	The colour picker’s popup trigger.
`swatches`	The container that holds the swatches.
`swatch`	The individual swatches in the colour picker.
`grid`	The colour grid.
`grid-handle`	The colour grid’s handle.
`slider`	The hue and opacity sliders.
`slider-thumb`	The hue and opacity slider thumbs.
`hue-slider`	The hue slider.
`hue-slider-thumb`	The hue slider’s thumb.
`opacity-slider`	The opacity slider.
`opacity-slider-thumb`	The opacity slider’s thumb.
`preview`	The preview colour.
`input`	The text input.
`copy-button`	The text input’s copy button.
`copy-button-button`	The `button` part of the text input’s copy button.
`eyedropper-button`	The eyedropper button.
`eyedropper-button-base`	The eyedropper button’s `button` part.
`eyedropper-button-prefix`	The eyedropper button’s `prefix` part.
`eyedropper-button-label`	The eyedropper button’s `label` part.
`eyedropper-button-suffix`	The eyedropper button’s `suffix` part.
`format-button`	The format switch button.
`format-button-base`	The format switch button’s `button` part.
`format-button-prefix`	The format switch button’s `prefix` part.
`format-button-label`	The format switch button’s `label` part.
`format-button-suffix`	The format switch button’s `suffix` part.

Learn more about customising CSS parts.

Animations#

Name	Description
`colorPicker.show`	The animation to use when showing the colour picker popup.
`colorPicker.hide`	The animation to use when hiding the colour picker popup.

Learn more about customising animations.

Importing#

If you’re using the autoloader or the standard loader, you can skip this section. But if you’re cherry picking, you can use any of the following snippets to import this component.

CDN (script tag)

CDN (import)

npm (import)

To manually import this component from the CDN, copy this code snippet and paste it in your HTML.

  <script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/color-picker/color-picker.js"></script> 

To manually import this component from the CDN, copy this code snippet and paste it in your JavaScript file.

  import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/color-picker/color-picker.js"; 

To manually import this component from npm, copy this code snippet and paste it in your JavaScript file.

import "placer-toolkit/dist/components/color-picker/color-picker.js";

Dependencies#

This component automatically imports these components: