Color Picker

<quiet-color-picker>

stable

since 1.0

Color pickers provide an interface for selecting a color using a two-dimension slider for luminosity and saturation and regular sliders for hue and opacity.

<quiet-color-picker 
  label="Select a color"
  description="Your preferences will be saved."
  name="color"
  value="#7578c5" 
  with-opacity
  with-eye-dropper
  swatches="
    #09090b #71717a #ef4444 #f97316 
    #f59e0b #eab308 #84cc16 #22c55e 
    #10b981 #14b8a6 #06b6d4 #3b82f6 
    #6366f1 #a855f7 #d946ef #ec4899
  "  
></quiet-color-picker>

Examples Jump to heading

Labels and descriptions Jump to heading

You can use the label and description attributes to provide plain text labels and descriptions for the color picker. If you want to provide HTML, use the label and description slots instead.

For more information, visit our website.

<quiet-color-picker name="color" label="Select a color">
  <span slot="description">
    For more information, <a href="https://example.com/" target="_blank">visit our website</a>.
  </span>
</quiet-color-picker>

Setting an initial value Jump to heading

Use the value attribute to provide an initial value for the color picker. You can specify values in a variety of formats as well as CSS colors names. Parsing of color values is very permissive. See the TinyColor docs for more details on acceptable color formats.

<quiet-color-picker 
  label="Select a color"
  name="color" 
  value="#71e0f3"
>
</quiet-color-picker>

Enabling opacity Jump to heading

Add the with-opacity attribute to allow the user to adjust transparency.

<quiet-color-picker 
  label="Select a color"
  name="color"
  value="#ce2380cc" 
  with-opacity 
></quiet-color-picker>

Enabling the eye dropper Jump to heading

Add the with-eye-dropper attribute to show the eye dropper button, which allows the user to select a color from anywhere on the screen.

<quiet-color-picker 
  label="Select a color"
  name="color"
  with-eye-dropper
></quiet-color-picker>

The EyeDropper API is only available in supportive browsers.

Showing swatches Jump to heading

Set the swatches attribute to one or more space-delimited hex colors or CSS color names, e.g. lightblue, to show as preset swatches below the color picker. This is useful for providing users with access to recent colors or a predefined color palette.

<quiet-color-picker
  label="Select a color"
  name="color"
  swatches="
    #09090b #71717a #ef4444 #f97316 
    #f59e0b #eab308 #84cc16 #22c55e 
    #10b981 #14b8a6 #06b6d4 #3b82f6 
    #6366f1 #a855f7 #d946ef #ec4899
  "
></quiet-color-picker>

Setting the format Jump to heading

Use the format attribute to set the format of the value. Valid options include hex (default), rgb, and hsl.

<quiet-color-picker 
  label="Select a color"
  name="color"
  value="#ffcc00"
  format="rgb"
  id="color-picker__format"
></quiet-color-picker>

<script>
  const colorPicker = document.getElementById('color-picker__format');

  // This will output an RGB string when the color changes
  colorPicker.addEventListener('quiet-change', () => {
    console.log(colorPicker.value);
  });
</script>

You can set the color picker's value using any format and it will automatically be converted to the format specified by the format attribute.

Getting the value programmatically Jump to heading

If you need to access the value in a specific format, use the getValueAs() method. You can pass rgb (default), hsl, hex, or hex8 to get a corresponding value.

For rgb, an object with { r, g, b, a } properties will be returned where r, g, and b range from 0-255 and a (alpha) ranges from 0–1. For hsl, an object with { h, s, l, a } properties will be returned where h ranges from 0–360 and s, l, and a range from 0–1. For hex and hex8, a string in the format of #RRGGBB and #RRGGBBAA will be returned, respectively.

<quiet-color-picker 
  label="Select a color"
  name="color"
  value="tomato"
  format="rgb"
  id="color-picker__object"
></quiet-color-picker>

<script>
  const colorPicker = document.getElementById('color-picker__object');

  // Outputs two objects when the color changes
  colorPicker.addEventListener('quiet-change', () => {
    console.log(
      colorPicker.getValueAs('rgb'),
      colorPicker.getValueAs('hex'),
      colorPicker.getValueAs('hex8'),
      colorPicker.getValueAs('hsl')
    );
  });
</script>

Changing the size Jump to heading

Use the size attribute to change the color pickers's size.

<quiet-select label="Select a size" style="max-width: 18rem; margin-block-end: 2rem;">
  <option value="xs">Extra small</option>
  <option value="sm">Small</option>
  <option value="md">Medium</option>
  <option value="lg">Large</option>
  <option value="xl">Extra large</option>
</quiet-select>

<quiet-color-picker 
  size="xs" 
  label="Color picker sizes"
    swatches="
    #09090b #71717a #ef4444 #f97316 
    #f59e0b #eab308 #84cc16 #22c55e 
    #10b981 #14b8a6 #06b6d4 #3b82f6 
    #6366f1 #a855f7 #d946ef #ec4899
  "  
  with-opacity
  with-eye-dropper
  id="color-picker__size"
></quiet-color-picker>

<script>
  const colorPicker = document.getElementById('color-picker__size');
  const select = colorPicker.previousElementSibling;

  select.addEventListener('quiet-change', () => {
    colorPicker.size = select.value;
  });  
</script>

Disabling Jump to heading

To disable a color picker, add the disabled attribute.

<quiet-color-picker 
  label="Select a color"
  disabled
  name="color"
  value="#6366f1"
  with-opacity 
  swatches="
    #09090b #71717a #ef4444 #f97316 
    #f59e0b #eab308 #84cc16 #22c55e 
    #10b981 #14b8a6 #06b6d4 #3b82f6 
    #6366f1 #a855f7 #d946ef #ec4899  
  "
></quiet-color-picker>

Using custom validation Jump to heading

Color pickers don't have built-in validation attributes like many other form controls. However, you can use the custom-validity attribute to make the color picker invalid and show a custom error message on submit. To clear the error, remove the attribute or set it to an empty string.

<form action="about:blank" method="get" target="_blank">
  <quiet-color-picker
    label="Select a color"
    name="color"
    description="This field will be invalid until the custom-validity attribute is removed"
    custom-validity="Not so fast, bubba!"
  ></quiet-color-picker>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
</form>

Most validation attributes work exactly like their native counterparts. However, the custom-validity attribute is offered in lieu of the setCustomValidity() method. This allows you to declaratively set custom errors instead of having to call a method with JavaScript.

Styling validation Jump to heading

You can style valid and invalid sliders using the :valid and :invalid pseudo classes.

              
                Submit
                Reset

<form action="about:blank" method="get" target="_blank" class="color-picker__validation-pseudo">
  <quiet-color-picker
    label="Select a color"
    name="color"
    value="#ff0000"
    custom-validity="The selected color must be white or black"
  ></quiet-color-picker>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .color-picker__validation-pseudo {
    quiet-color-picker:valid {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: 1rem;
    }

    quiet-color-picker:invalid {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: 1rem;
    }
  }
</style>

<script>
  const form = document.querySelector('.color-picker__validation-pseudo');
  const colorPicker = form.querySelector('quiet-color-picker');

  async function updateValidity() {
    await colorPicker.updateComplete;
    const isValid = ['#ffffff', '#000000'].includes(colorPicker.value);
    colorPicker.customValidity = isValid ? '' : 'Select white or black only';
  }

  colorPicker.addEventListener('quiet-input', () => updateValidity());
  form.addEventListener('reset', () => updateValidity());
</script>

However, these selectors will match even before the user has had a chance to fill out the form. More often than not, you'll want to use the user-valid and user-invalid custom states instead. This way, validation styles are only shown after the user interacts with the form control or when the form is submitted.

              
                Submit
                Reset

<form action="about:blank" method="get" target="_blank" class="color-picker__validation-custom">
  <quiet-color-picker
    label="Select a color"
    name="color"
    value="#ff0000"
    custom-validity="The selected color must be white or black"
  ></quiet-color-picker>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .color-picker__validation-custom {
    quiet-color-picker:state(user-valid) {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: 1rem;
    }

    quiet-color-picker:state(user-invalid) {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: 1rem;
    }
  }
</style>

<script>
  const form = document.querySelector('.color-picker__validation-custom');
  const colorPicker = form.querySelector('quiet-color-picker');

  async function updateValidity() {
    await colorPicker.updateComplete;
    const isValid = ['#ffffff', '#000000'].includes(colorPicker.value);
    colorPicker.customValidity = isValid ? '' : 'Select white or black only';
  }

  colorPicker.addEventListener('quiet-input', () => updateValidity());
  form.addEventListener('reset', () => updateValidity());
</script>

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN

npm

To manually import <quiet-color-picker> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet@1.0.0/dist/components/color-picker/color-picker.js';

To manually import <quiet-color-picker> from npm, use the following code.

import '@quietui/quiet/dist/components/color-picker/color-picker.js';

Slots Jump to heading

Color Picker supports the following slots. Learn more about using slots

Name	Description
`label`	The color picker's label. For plain-text labels, you can use the `label` attribute instead.
`description`	The color picker's description. For plain-text descriptions, you can use the `description` attribute instead.

Properties Jump to heading

Color Picker has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute	Description	Type	Default
`associatedForm`	A reference to the `<form>` associated with the form control, or `null` if no form is associated.	`HTMLFormElement null`	`null`
`label`	The color picker's label. If you need to provide HTML in the label, use the `label` slot instead.	`string`
`description`	The color picker's description. If you need to provide HTML in the description, use the `description` slot instead.	`string`
`name`	The name of the color picker. This will be submitted with the form as a name/value pair.	`string`
`value`	The color picker's value.	`string`	`''`
`format`	The format to use for the value.	`'hex' 'rgb' 'hsl'`	`'hex'`
`disabled`	Disables the color picker.	`boolean`	`false`
`size`	The color picker's size.	`'xs' 'sm' 'md' 'lg' 'xl'`	`'md'`
`swatches`	One or more space-delimited hex colors or CSS color names, e.g. `lightblue`, to show as preset swatches below the color picker.	`string`	`''`
`form`	The form to associate this control with. If omitted, the closest containing `<form>` will be used. The value of this attribute must be an ID of a form in the same document or shadow root.	`string`
`customValidity` `custom-validity`	You can provide a custom error message to force the color picker to be invalid. To clear the error, set this to an empty string.	`string`	`''`
`withOpacity` `with-opacity`	Enables the opacity slider.	`boolean`	`false`
`withEyeDropper` `with-eye-dropper`	Enables the eye dropper button. Only available in supportive browsers.	`boolean`	`false`

Methods Jump to heading

Color Picker supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods

Name	Description	Arguments
`focus()`	Sets focus to the color picker.
`blur()`	Removes focus from the color picker.
`getValueAs()`	Gets the current value as a hex string, a hex8 string, an RGB object, or an HSL object. RBG objects have `r`, `g`, and `b` properties ranging from 0–255 and an `a` property (representing opacity) that ranges from 0-1. HSL objects have an `h` property ranging from `0-359` and `s`, `l`, and `a` properties ranging from 0–1.	`format: 'hex' <br> 'hex8' <br> 'hsl' <br> 'rgb'`
`checkValidity()`	Checks if the form control has any restraints and whether it satisfies them. If invalid, `false` will be returned and the `invalid` event will be dispatched. If valid, `true` will be returned.
`reportValidity()`	Checks if the form control has any restraints and whether it satisfies them. If invalid, `false` will be returned and the `invalid` event will be dispatched. In addition, the problem will be reported to the user. If valid, `true` will be returned.

Events Jump to heading

Color Picker dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name	Description
`change`
`input`
`quiet-change`	Emitted when the user commits changes to the color picker's value.
`quiet-input`	Emitted when the color picker receives input. This can fire very frequently during dragging, so avoid doing expensive operations in the handler. If you don't live feedback, use the `quiet-change` event instead.

CSS parts Jump to heading

Color Picker exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name	Description	CSS selector
`label`	The element that contains the color picker's label.	`::part(label)`
`description`	The element that contains the color picker's description.	`::part(description)`
`picker`	The element the wraps the color picker (excluding the label and description).	`::part(picker)`
`color-slider`	The 2d color slider.	`::part(color-slider)`
`color-slider-thumb`	The color slider's thumb.	`::part(color-slider-thumb)`
`controls`	The container that wraps the sliders and preview.	`::part(controls)`
`sliders`	The container that wraps the hue and opacity slider.	`::part(sliders)`
`hue-slider`	The slider that controls the color's hue.	`::part(hue-slider)`
`hue-slider__label`	The hue slider's `label` part.	`::part(hue-slider__label)`
`hue-slider__description`	The hue slider's `description` part.	`::part(hue-slider__description)`
`hue-slider__slider`	The hue slider's `slider` part.	`::part(hue-slider__slider)`
`hue-slider__track`	The hue slider's `track` part.	`::part(hue-slider__track)`
`hue-slider__indicator`	The hue slider's `indicator` part.	`::part(hue-slider__indicator)`
`hue-slider__thumb`	The hue slider's `thumb` part.	`::part(hue-slider__thumb)`
`opacity-slider`	The slider that controls the color's opacity.	`::part(opacity-slider)`
`opacity-slider__label`	The opacity slider's `label` part.	`::part(opacity-slider__label)`
`opacity-slider__description`	The opacity slider's `description` part.	`::part(opacity-slider__description)`
`opacity-slider__slider`	The opacity slider's `slider` part.	`::part(opacity-slider__slider)`
`opacity-slider__track`	The opacity slider's `track` part.	`::part(opacity-slider__track)`
`opacity-slider__indicator`	The opacity slider's `indicator` part.	`::part(opacity-slider__indicator)`
`opacity-slider__thumb`	The opacity slider's `thumb` part.	`::part(opacity-slider__thumb)`
`eye-dropper-button`	The eye dropper button, a `<quiet-button>` element.	`::part(eye-dropper-button)`
`preview-button`	The button that shows a preview of the current color, a `<quiet-button>` element.	`::part(preview-button)`
`swatches`	The element that contains swatches.	`::part(swatches)`
`swatch`	Each individual swatch.	`::part(swatch)`

Custom States Jump to heading

Color Picker has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name	Description	CSS selector
`disabled`	Applied when the color picker is disabled.	`:state(disabled)`
`focused`	Applied when the color picker has focus.	`:state(focused)`
`user-valid`	Applied when the color picker is valid and the user has sufficiently interacted with it.	`:state(user-valid)`
`user-invalid`	Applied when the color picker is invalid and the user has sufficiently interacted with it.	`:state(user-invalid)`

Dependencies Jump to heading

Color Picker automatically imports the following elements. Sub-dependencies are also included in this list.

Color Picker

Examples Jump to heading #

Labels and descriptions Jump to heading #

Setting an initial value Jump to heading #

Enabling opacity Jump to heading #

Enabling the eye dropper Jump to heading #

Showing swatches Jump to heading #

Setting the format Jump to heading #

Getting the value programmatically Jump to heading #

Changing the size Jump to heading #

Disabling Jump to heading #

Using custom validation Jump to heading #

Styling validation Jump to heading #

API Jump to heading #

Importing Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Methods Jump to heading #

Events Jump to heading #

CSS parts Jump to heading #

Custom States Jump to heading #

Dependencies Jump to heading #