yet-another-color-picker

yet-another-color-picker

A color picker web component.

This package’s files are distributed in the ES module format and have not been transpiled. It uses lit-html which is not bundled with the package.

Links:

• demo
• npmjs.com/package/yet-another-color-picker
  • on BundlePhobia
• github.com/kleinfreund/yet-another-color-picker
  • code of conduct
  • contributing guidelines
• as a Vue component: vue-accessible-color-picker

Contents

• Installation & usage
  • As npm package
  • As plain files directly in the browser (no build step)
• Documentation
  • Technical summary
  • Properties
    • activeFormat
    • alphaChannel
    • color
    • defaultFormat
    • id
    • visibleFormats
  • Methods
    • copyColor()
    • switchFormat()
  • Events
    • color-change
• Versioning
• Contributing
• Design
• To do

Installation & usage

As npm package

1. Install the package.

   npm install yet-another-color-picker
   

2. Import the module to define the custom element.

   HTML:

   <color-picker></color-picker>
   

   JavaScript:

   import 'yet-another-color-picker'
   

3. Make sure to also load the color picker styles.

   HTML:

   <link rel="stylesheet" href="./node_modules/yet-another-color-picker/dist/ColorPicker.css">
   

As plain files directly in the browser (no build step)

1. Download the files.

   curl --remote-name-all 'https://cdn.jsdelivr.net/npm/yet-another-color-picker@latest/dist/ColorPicker.{js,css}'
   

2. Define an import map for lit-html.

   Since this package does not bundle its dependencies (e.g. lit-html), the distribution files contain imports from bare module specifiers (e.g. import { render } from 'lit-html'). Browsers don't understand bare module specifiers by default, but with import maps, you can teach them.

   HTML:

   <script type="importmap">
   	{
   		"imports": {
   			"lit-html": "https://unpkg.com/lit-html@latest/lit-html.js?module"
   		}
   	}
   </script>
   

   This will make imports like the one mentioned above behave as if they reference the provided URL (e.g. import { render } from 'lit-html' will behave like import { render } from 'https://unpkg.com/lit-html@latest/lit-html.js?module'). And that browsers do undertand.

3. Import the module to define the custom element.

   HTML:

   <color-picker></color-picker>
   

   JavaScript:

   import './ColorPicker.js'
   

4. Make sure to also load the color picker styles.

   HTML:

   <link rel="stylesheet" href="./ColorPicker.css">
   

Documentation

Properties

Each of the following properties can also be set via its corresponding attribute.

Note: Changing an attribute will be synced to its corresponding property; however, changing a property will not be synced to its corresponding attribute.

activeFormat

• Description: The currently active format. Changes when interacting with the “Switch format” button or when calling switchFormat().

• Type: VisibleColorFormat

• Required: false

• Default: 'hsl'

• Attribute: —

• Usage:

  JavaScript:

  colorPicker.activeFormat = 'hwb'
  

alphaChannel

• Description: Whether to show input controls for a color’s alpha channel. If set to 'hide', the alpha range input and the alpha channel input are hidden, the “Copy color” button will copy a CSS color value without alpha channel, and the object emitted in a color-change event will have a cssColor property value without alpha channel.

• Type: 'show' | 'hide'

• Required: false

• Default: 'show'

• Attribute: alpha-channel

• Usage:

  HTML:

  <color-picker alpha-channel="hide"></color-picker>
  

  JavaScript:

  colorPicker.alphaChannel = 'hide'
  

color

• Description: Sets the color of the color picker. You can pass any valid CSS color string.

• Type: string | ColorHsl | ColorHsv | ColorHwb | ColorRgb (for string, any valid CSS color string will work)

• Required: false

• Default: '#ffffffff'

• Attribute: color

• Usage:

  HTML:

  <color-picker color="hsl(270 100% 50% / 0.8)"></color-picker>
  

  HTML:

  <color-picker color="#f80b"></color-picker>
  

  JavaScript:

  colorPicker.color = 'hsl(270 100% 50% / 0.8)'
  

  JavaScript:

  colorPicker.color = { h: 0.75, s: 1, l: 0.5, a: 0.8 }
  

defaultFormat

• Description: The color format to show by default when rendering the color picker. Must be one of the formats specified in visibleFormats.

• Type: VisibleColorFormat

• Required: false

• Default: 'hsl'

• Attribute: default-format

• Usage:

  HTML:

  <color-picker default-format="hwb"></color-picker>
  

  JavaScript:

  colorPicker.defaultFormat = 'hwb'
  

id

• Description: The ID value will be used to prefix all input elements’ id and label elements’ for attribute values. Make sure to set this if you use multiple instances of the component on a page.

• Type: string

• Required: false

• Default: 'color-picker'

• Attribute: id

• Usage:

  HTML:

  <color-picker id="color-picker-1"></color-picker>
  

  JavaScript:

  colorPicker.id = 'color-picker-1'
  

visibleFormats

• Description: A list of visible color formats. Controls for which formats the color input elements are shown and in which order the formats will be cycled through when activating the format switch button.

• Type: VisibleColorFormat (an array of VisibleColorFormats)

• Required: false

• Default: ['hex', 'hsl', 'hwb', 'rgb']

• Attribute: visibleFormats

• Usage:

  HTML:

  <color-picker visible-formats="hsl,hwb"></color-picker>
  

  JavaScript:

  colorPicker.visibleFormats = ['hsl', 'hwb']
  

Methods

copyColor()

• Description: Copies the current color (determined by the active color format).

  This method behaves the same as activating the “Copy color” button.

  Only works in secure browsing contexts (i.e. HTTPS).

• Return type: Promise<void> (the promise returned by calling window.navigator.clipboard.writeText)

• Usage:

  JavaScript:

  colorPicker.copyColor()
  

switchFormat()

• Description: Sets the next active color format by cycling through colorPicker.visibleFormats. This method behaves the same as activating the “Switch format” button. To set a specific color format, use the activeFormat property.

• Return type: void

• Usage:

  JavaScript:

  colorPicker.switchFormat()
  

Events

color-change

• Description: The custom event that is emitted each time the internal colors object is updated.

• Type: CustomEvent<ColorChangeDetail>

• Data: The custom event emits an object whose detail property contains both the internal colors object and a CSS color value as a string based on the currently active format. The cssColor property will respect alpha-channel.

  {
  	colors: {
  		hex: string
  		hsl: ColorHsl
  		hsv: ColorHsv
  		hwb: ColorHwb
  		rgb: ColorRgb
  	}
  	cssColor: string
  }
  

• Usage:

  HTML:

  <color-picker color="hsl(270 100% 50% / 0.8)"></color-picker>
  

  JavaScript:

  import 'yet-another-color-picker'
  
  const colorPicker = document.querySelector('color-picker')
  colorPicker.addEventListener('color-change', function (event) {
  	console.log(event.detail)
  })
  

Versioning

This package uses semantic versioning.

Contributing

See CONTRIBUTING.md.

Design

The color picker consists of the following main elements:

• Color space:

  For fine-tuning the saturation and lightness/value, a slice of the HSV cylinder for the currently selected hue is shown.

  The HSV cylinder is more convenient for this task than the HSL cylinder as it shows a color at 100% saturation and 100% value in the top right corner (i.e. one can drag the color space thumb into the corner as a quasi shortcut). The HSL cylinder’s slice has this color at the halfway point of the Y axis (i.e. at 50% lightness) which isn’t easy to select.

• Hue slider:

  A slider for selecting the current hue. This rotates the HSV cylinder; thus, it changes the slice of the HSV cylinder that’s shown in the color space.

• Alpha slider:

  A slider for selecting the current alpha value.

• Copy button:

  Copies the color formatted as a CSS color string in the active format.

• Color inputs:

  A set of text fields which allow you to enter the individual components of each color. The text fields are shown based on the active format.

• Switch format button:

  Cycles through the available color formats (currently HEX, HSL, HWB, and RGB).

To do

• Document browser usage via import maps (https://caniuse.com/import-maps).
• Re-consider how state is recomputed internally.
• Re-consider optimization strategy following https://lit.dev/docs/tools/publishing/#don't-bundle-minify-or-optimize-modules (see also https://open-wc.org/guides/developing-components/publishing/#do-not-minify).

Changelog

2.0.0 (2023-07-24)

⚠ BREAKING CHANGES

• Stops bundling lit-html so applications can deduplicate the dependency in their build process. This removes the ability to use the package directly in the browser without a build step. To continue doing so, use import maps to map lit-html to a CDN URL to address this issue (see documentation for instructions).
• Changes the file name and location of the color picker typings from types/index.d.ts to dist/ColorPicker.d.ts. Please update your imports.
• Removes the data- prefix from all color picker attributes (data-alpha-channel → alpha-channel, data-color → color, data-default-format → default-format, data-visible-channels → visible-channels).
• No longer sets color picker attributes to their respective default values. As a replacement, their associated properties will now be set to those default values.
• Makes the color picker self-define (with the local name "color-picker") when importing the module. This removes the need for calling window.customElements.define('color-picker', ColorPicker) manually in application code.

Features

• adds copyColor() method (42ebe28)
• adds support for properties (a3737c4)
• adds switchFormat() method (0574aa1)
• self-defines custom element as color-picker on import (a1bd609)

Bug Fixes

• not setting box-sizing on the color picker element (752d7d4)

Code Refactoring

• converts code base to typescript (be55758)

Miscellaneous Chores

• removes "data-" prefix from color picker attributes (318bb3f)
• stops bundling lit-html (facdaba)