Skip to content

kleinfreund/yet-another-color-picker

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

185 Commits
.github
.github
 
 
.husky
.husky
 
 
dist
dist
 
 
src
src
 
 
.editorconfig
.editorconfig
 
 
.gitattributes
.gitattributes
 
 
.gitignore
.gitignore
 
 
.nvmrc
.nvmrc
 
 
CHANGELOG.md
CHANGELOG.md
 
 
CODE_OF_CONDUCT.md
CODE_OF_CONDUCT.md
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
LICENSE.txt
LICENSE.txt
 
 
README.md
README.md
 
 
changelog-template-commit.hbs
changelog-template-commit.hbs
 
 
commitlint.config.js
commitlint.config.js
 
 
eslint.config.js
eslint.config.js
 
 
index.html
index.html
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
release.config.js
release.config.js
 
 
standalone.html
standalone.html
 
 
tsconfig.json
tsconfig.json
 
 
tsup.config.ts
tsup.config.ts
 
 
vite.config.js
vite.config.js
 
 

Repository files navigation

yet-another-color-picker

Tests passing

A color picker web component.

  • Form-associated custom element (i.e. it works in forms via the ElementInternals API)
  • Distributed is ES module format
  • Not transpiled
  • Uses lit-html (as a peer dependency)

Links:

Contents

Installation & usage

As npm package

  1. Install the package (and its peer dependencies).

    npm install yet-another-color-picker lit-html@^3.0.0

    Note: this web component is rendered using lit-html which will have to be installed as well.

  2. Import the module to define the custom element.

    JavaScript:

    import 'yet-another-color-picker'

  3. Load the stylesheet.

    HTML:

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

  4. Use the color-picker custom element.

    HTML:

    <color-picker></color-picker>

Complete example:

<!DOCTYPE html>
<html lang="en">

<head>
	<meta charset="utf-8" />
	<meta name="viewport" content="width=device-width,initial-scale=1.0" />

	<title>color picker demo</title>

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

<body>
	<color-picker></color-picker>

	<script type="module">
		import 'yet-another-color-picker'

		const colorPicker = document.querySelector('color-picker')
		colorPicker.addEventListener('color-change', function (event) {
			console.log(event.detail)
		})
	</script>
</body>

</html>

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,d.ts}'

    1. 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.

      Add the following to your HTML:

      HTML:

      <script type="importmap">
	{
		"imports": {
			"lit-html": "https://cdn.jsdelivr.net/npm/lit-html@^3.0.0"
		}
	}
</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://cdn.jsdelivr.net/npm/lit-html@^3.0.0').

  2. Import the module to define the custom element.

    JavaScript:

    import './ColorPicker.js'

  3. Load the stylesheet.

    HTML:

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

  4. Use the color-picker custom element.

    HTML:

    <color-picker></color-picker>

Complete example:

<!DOCTYPE html>
<html lang="en">

<head>
	<meta charset="utf-8" />
	<meta name="viewport" content="width=device-width,initial-scale=1.0" />

	<title>color picker demo</title>

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

<body>
	<color-picker></color-picker>

	<script type="importmap">
		{
			"imports": {
				"lit-html": "https://cdn.jsdelivr.net/npm/lit-html@^3.0.0"
			}
		}
	</script>
	<script type="module">
		import './ColorPicker.js'

		const colorPicker = document.querySelector('color-picker')
		colorPicker.addEventListener('color-change', function (event) {
			console.log(event.detail)
		})
	</script>
</body>

</html>

Documentation

Attributes

In the following sections, the web component's IDL and content attibutes, are documented.

Note: Setting a content attribute will be reflected by its corresponding IDL attribute; however, setting an IDL attribute will not be reflected by its corresponding content attribute.

alphaChannel

  • Description: Whether to show 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'

  • Content attribute: alpha-channel

  • Usage:

    JavaScript:

     colorPicker.alphaChannel = 'hide'

    HTML:

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

defaultValue

  • Description: Set the color picker's current color as long as the color wasn't changed by the user already.

  • Type: string

  • Required: false

  • Default: ''

  • Content attribute: value

  • Usage:

    JavaScript:

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

    HTML:

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

    HTML:

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

disabled

  • Description: Disables the color picker.

  • Type: boolean

  • Required: false

  • Default: false

  • Content attribute: disabled

  • Usage:

    JavaScript:

     colorPicker.disabled = true

    HTML:

     <color-picker disabled></color-picker>

format

  • Description: The current color format. Also changes when interacting with the “Switch format” button or when calling switchFormat().

  • Type: VisibleColorFormat

  • Required: false

  • Default: 'hsl'

  • Content attribute: format

  • Usage:

    JavaScript:

     colorPicker.format = 'hwb'

    HTML:

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

id

  • Description: This value will be used to prefix any of the color picker’s form-associated elements’ id and for attribute values. Make sure to set this if you use multiple instances of the component on a page.

    Note: The IDL attribute id of form-associated elements is reflected by its content attribute.

  • Type: string

  • Required: false

  • Default: 'color-picker'

  • Content attribute: id

  • Usage:

    JavaScript:

     colorPicker.id = 'color-picker-1'

    HTML:

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

name

  • Description: Name of the color picker (used when the color picker is part of a form).

    Note: The IDL attribute name of form-associated elements is reflected by its content attribute.

  • Type: string

  • Required: false

  • Default: ''

  • Content attribute: name

  • Usage:

    JavaScript:

     colorPicker.name = 'color-picker'

    HTML:

     <color-picker name="color-picker"></color-picker>

readOnly

  • Description: Makes the color picker read-only.

  • Type: boolean

  • Required: false

  • Default: false

  • Content attribute: readonly

  • Usage:

    JavaScript:

     colorPicker.readonly = true

    HTML:

     <color-picker readonly></color-picker>

value

  • Description: The current color of the color picker.

    The value getter will return the current color as a string (formatted as a CSS RGB color, e.g. 'rgb(127.5 0 255 / 0.8)'). This is also the form value used in form submission.

    The value setter accepts a string (any valid CSS color in a known format works, e.g. 'hsl(270 100% 50% / 0.8)') or an object (e.g. { h: 270, s: 100, l: 50, a: 0.8 }).

  • Type: string | ColorHsl | ColorHwb | ColorRgb

  • Required: false

  • Default: 'rgb(255 255 255 / 1)'

  • Content attribute: None. The value IDL attribute doesn't directly reflect a content attribute. However, the value IDL attribute does reflect the defaultValue IDL attribute as long as the dirty flag isn't set.

  • Usage:

    JavaScript:

     colorPicker.value = 'hsl(270 100% 50% / 0.8)'
 colorPicker.value
 //> 'rgb(127.5 0 255 / 0.8)'

    JavaScript:

     colorPicker.value = { h: 270, s: 100, l: 50, a: 0.8 }

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']

  • Content attribute: visible-formats

  • Usage:

    JavaScript:

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

    HTML:

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

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 format property.

  • Return type: void

  • Usage:

    JavaScript:

     colorPicker.switchFormat()

Events

change

  • Description: The change event is fired when the color is changed.
  • Type: Event

color-change

  • Description: The color-change event is fired when the color is changed.

  • Type: CustomEvent<ColorChangeDetail>

  • Data: 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 respects the alphaChannel IDL attribute.

     {
 	colors: {
 		hex: string
 		hsl: ColorHsl
 		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)
 })

 colorPicker.value = 'rebeccapurple'

color-copy

  • Description: The color-copy event is fired once a copy operation succeeded.

  • Type: CustomEvent<ColorChangeDetail>

  • Data: Emits the same event data as the color-change event.

  • 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-copy', function (event) {
 	console.log(event.detail)
 })

 colorPicker.copyColor()

input

  • Description: The input event is fired when the color is changed.
  • Type: Event

Theming

You can customize the GUI of the color picker using CSS custom properties:

:root {
	--cp-color-focus: tomato;
	--cp-width-border: 2px;
}

Available custom properties and their default values:

Custom property Default value
--cp-color-background-input #fff
--cp-color-background #fff
--cp-color-border #000
--cp-color-focus #19f
--cp-color-text-input currentColor
--cp-color-text currentColor
--cp-font-family -apple-system, BlinkMacSystemFont, Segoe UI, Arial, sans-serif
--cp-font-size 0.8em
--cp-spacing 6px
--cp-width-border 1px
--cp-width-color-space 300px

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

About

A color picker web component.

yet-another-color-picker.netlify.app

Topics

web-component color-picker

Resources

Readme

License

MIT license

Code of conduct

Code of conduct
Activity

Stars

0 stars

Watchers

3 watching

Forks

0 forks
Report repository

Releases 8

v4.0.1 Latest
Dec 17, 2024
+ 7 releases

Packages

No packages published

Contributors 2

Languages