vanilla-colorful

repository·master·Indexed 21 days ago

https://github.com/web-padawan/vanilla-colorful

A lightweight, framework-agnostic color picker library ported from react-colorful to vanilla Custom Elements. It provides performant and accessible Web Components for various color models, including HEX, HSL, HSV, and RGB. The library includes specialized elements like <hex-color-picker>, <hex-input>, and various string-based pickers, all customizable via CSS Shadow Parts. It features built-in TypeScript support and is compatible with modern browsers supporting Custom Elements and Shadow DOM.

Tokens
8K
Snippets
25
Records
29
Agent score
71%

What's inside vanilla-colorful

  1. Use different color models

    master

    While the default is HEX, vanilla-colorful provides 12 additional color picker bundles for different models (HSL, HSV, RGB, etc.). Each bundle corresponds to a specific HTML element and value format.

    Available Pickers Reference

    File to importHTML elementValue example
    "hex-color-picker.js"<hex-color-picker>"#ffffff"
    "hex-alpha-color-picker.js"<hex-alpha-color-picker>"#ffffff88"
    "hsl-color-picker.js"<hsl-color-picker>{ h: 0, s: 0, l: 100 }
    "hsl-string-color-picker.js"<hsl-string-color-picker>"hsl(0, 0%, 100%)"
    "hsla-color-picker.js"<hsla-color-picker>{ h: 0, s: 0, l: 100, a: 1 }
    "hsla-string-color-picker.js"<hsla-string-color-picker>"hsla(0, 0%, 100%, 1)"
    "hsv-color-picker.js"<hsv-color-picker>{ h: 0, s: 0, v: 100 }
    "hsv-string-color-picker.js"<hsv-string-color-picker>"hsv(0, 0%, 100%)"
    "hsva-color-picker.js"<hsva-color-picker>{ h: 0, s: 0, v: 100, a: 1 }
    "hsva-string-color-picker.js"<hsva-string-color-picker>"hsva(0, 0%, 100%, 1)"
    "rgb-color-picker.js"<rgb-color-picker>{ r: 255, g: 255, b: 255 }
    "rgba-color-picker.js"<rgba-color-picker>{ r: 255, g: 255, b: 255, a: 1 }
    "rgb-string-color-picker.js"<rgb-string-color-picker>"rgb(255, 255, 255)"
    "rgba-string-color-picker.js"<rgba-string-color-picker>"rgba(255, 255, 255, 1)"

    Example: Using RGBA

    <rgba-color-picker></rgba-color-picker>
    <script type="module">
      import 'vanilla-colorful/rgba-color-picker.js';
    
      const picker = document.querySelector('rgba-color-picker');
      picker.color = { r: 50, g: 100, b: 150, a: 1 };
    </script>
  2. Use the default hex-color-picker

    master

    The default picker uses HEX strings (e.g., #ffffff) for input and output. To use it, import the package and listen for the color-changed event to react to user input.

    <hex-color-picker color="#1e88e5"></hex-color-picker>
    <script type="module">
      import 'vanilla-colorful';
    
      const picker = document.querySelector('hex-color-picker');
      
      // Listen for changes
      picker.addEventListener('color-changed', (event) => {
        const newColor = event.detail.value;
      });
    
      // Access current color via property
      console.log(picker.color);
    </script>
    <hex-color-picker color="#1e88e5"></hex-color-picker>
    <script type="module">
      import 'vanilla-colorful';
    
      const picker = document.querySelector('hex-color-picker');
      picker.addEventListener('color-changed', (event) => {
        // get updated color value
        const newColor = event.detail.value;
      });
    
      // get current color value
      console.log(picker.color);
    </script>
  3. Use TypeScript with vanilla-colorful

    master

    The library has built-in TypeScript support and ships with its own types, so no additional installation is required. You can use the library's types to type your own variables or use the specific types associated with the custom elements you are using.

    For example, if you are using the <hsl-color-picker> element, you can import the HslColor type to ensure type safety for your color objects.

    import type { HslColor } from 'vanilla-colorful/hsl-color-picker';
    
    const myHslValue: HslColor = { h: 0, s: 0, l: 0 };
  4. Install vanilla-colorful

    master

    You can install vanilla-colorful via npm or use a CDN for direct browser usage.

    npm

    npm install vanilla-colorful --save

    CDN

    Use one of the following module scripts in your HTML:

    • unpkg.com: <script type="module" src="https://unpkg.com/vanilla-colorful?module"></script>
    • Skypack: <script type="module" src="https://cdn.skypack.dev/vanilla-colorful"></script>
    • JSPM: <script type="module" src="https://jspm.dev/vanilla-colorful"></script>
    • ESM.sh: <script type="module" src="https://esm.sh/vanilla-colorful"></script>
  5. Access typed event details in TypeScript

    master

    All included custom elements provide overrides for addEventListener and removeEventListener methods. This ensures that the detail property of the color-changed custom event is correctly typed, allowing you to access color properties (like a in RgbaColor) with full IDE autocompletion and type safety.

    const picker = document.querySelector('rgba-color-picker');
    
    // The event.detail.value is automatically typed based on the picker used
    picker.addEventListener('color-changed', (event) => {
      console.log(event.detail.value.a); // (property) RgbaColor.a: number
    });
  6. Use the hex-input element

    master

    The <hex-input> element provides a text field for typing or pasting HEX colors. It renders an unstyled <input> inside a slot, which you can style using part. You can also provide your own <input> as a child for full configuration.

    Properties

    PropertyDefaultDescription
    alphafalseAllows #rgba and #rrggbbaa color formats
    prefixedfalseEnables # prefix displaying
    color-The current color value

    Example

    <hex-input color="#1e88e5"></hex-input>
    <script type="module">
      import 'vanilla-colorful/hex-input.js';
    
      const input = document.querySelector('hex-input');
      input.addEventListener('color-changed', (event) => {
        const newColor = event.detail.value;
      });
    </script>
  7. Create a custom color picker using Base Classes

    master

    If you want to use a different tag name than the ones provided, you can import and extend the base classes. This allows you to create your own custom elements without registering the default ones.

    Example

    import { RgbBase } from 'vanilla-colorful/lib/entrypoints/rgb.js';
    
    customElements.define('custom-color-picker', class extends RgbBase {});
  8. Override picker styles with CSS Shadow Parts

    master

    You can customize the appearance of the color pickers using the ::part CSS pseudo-element. The following parts are available:

    • saturation: The saturation/lightness area.
    • hue: The hue slider.
    • saturation-pointer: The pointer in the saturation area.
    • hue-pointer: The pointer on the hue slider.

    Example

    hex-color-picker {
      height: 250px;
    }
    
    hex-color-picker::part(saturation) {
      bottom: 30px;
      border-radius: 3px 3px 0 0;
    }
    
    hex-color-picker::part(hue) {
      height: 30px;
      border-radius: 0 0 3px 3px;
    }
    
    hex-color-picker::part(saturation-pointer) {
      border-radius: 5px;
    }
    
    hex-color-picker::part(hue-pointer) {
      border-radius: 2px;
      width: 15px;
      height: inherit;
    }
  9. Parse CSS Hue angles

    master

    The parseHue function converts a numeric value and a CSS angle unit into a standard degree value (0-360).

    Supported units via angleUnits:

    • deg: (Default) 1 unit = 1 degree.
    • rad: Radians.
    • grad: Gradians.
    • turn: Turns.
    import { parseHue } from './src/lib/utils/convert';
    
    const degrees = parseHue('180', 'deg'); // 180
    const degreesFromRad = parseHue('3.14159', 'rad'); // ~180
  10. Use the <rgba-color-picker> custom element

    master

    The <rgba-color-picker> is a custom element used for selecting colors in RGBA format.

    Properties

    • color: An RgbaColor object representing the currently selected color.

    Events

    • color-changed: Fired whenever the selected color property changes.

    CSS Shadow Parts

    You can style the internal components of the picker using the ::part() pseudo-element with the following keys:

    • hue: The hue selector container.
    • saturation: The saturation selector container.
    • alpha: The alpha selector container.
    • hue-pointer: The pointer element for hue selection.
    • saturation-pointer: The pointer element for saturation selection.
    • alpha-pointer: The pointer element for alpha selection.
    <!-- HTML Usage -->
    <rgba-color-picker id="picker"></rgba-color-picker>
    
    <script>
      const picker = document.querySelector('#picker');
    
      // Listen for color changes
      picker.addEventListener('color-changed', (event) => {
        console.log('New color:', picker.color);
      });
    
      // Set an initial color
      picker.color = { r: 255, g: 0, b: 0, a: 1 };
    </script>
    
    <style>
      /* Example of styling via CSS parts */
      rgba-color-picker::part(hue-pointer) {
        width: 10px;
        height: 10px;
        border-radius: 50%;
      }
    </style>
  11. Use the <rgb-color-picker> custom element

    master

    The <rgb-color-picker> is a custom element used to select colors using the RGB object format.

    Properties

    • color: An RgbColor object representing the currently selected color.

    Events

    • color-changed: Fired whenever the selected color property changes.

    CSS Shadow Parts

    You can style the internal components of the picker using the ::part pseudo-element:

    • hue: The hue selector container.
    • saturation: The saturation selector container.
    • hue-pointer: The element representing the hue pointer.
    • saturation-pointer: The element representing the saturation pointer.
    <!-- HTML Usage -->
    <rgb-color-picker id="picker"></rgb-color-picker>
    
    <script>
      const picker = document.querySelector('#picker');
    
      // Listen for color changes
      picker.addEventListener('color-changed', (event) => {
        console.log('New color:', picker.color);
      });
    
      // Set a color programmatically
      picker.color = { r: 255, g: 0, b: 0 };
    </script>
    
    <!-- Styling via CSS Shadow Parts -->
    <style>
      rgb-color-picker::part(hue-pointer) {
        width: 10px;
        height: 10px;
        border-radius: 50%;
      }
    </style>