Vanilla Colorful Color Picker

Common errors

• Uncaught SyntaxError: Cannot use import statement outside a module

  cause The HTML `<script>` tag is missing `type="module"` when using ES Module imports directly in the browser.
  fix Add `type="module"` to your script tag: `<script type="module" src="./main.js"></script>` or use a bundler/CDN with module resolution.

• Uncaught ReferenceError: HexColorPicker is not defined

  cause The JavaScript file is attempting to use `HexColorPicker` (or other custom element classes) without first importing the `vanilla-colorful` module to register the custom elements.
  fix Ensure `import 'vanilla-colorful';` is at the top of your module, or `import { HexColorPicker } from 'vanilla-colorful';` if you're directly using the class.

• DOMException: Failed to execute 'define' on 'CustomElementRegistry': the name "hex-color-picker" has already been used with this registry

  cause The `vanilla-colorful` module is being imported and executed multiple times in the same context, attempting to define the same custom element twice.
  fix Ensure the `import 'vanilla-colorful';` statement runs only once. This can happen if you include the script multiple times, or if a build process duplicates module imports. Remove redundant imports.

Warnings

• breaking Starting with version 0.7.0, setting the `color` property programmatically on a picker component will no longer fire the `color-changed` event. This was changed to prevent infinite loops in reactive frameworks.
  Fix: If you need to react to programmatic color changes, implement separate logic or directly call your update function after setting the property. The `color-changed` event is strictly for user interactions.
• breaking In version 0.6.0, internal elements were simplified and the `color-changed` event typings were added. This might affect advanced users extending internal components or relying on previous internal structures.
  Fix: Review your custom implementations that extend `vanilla-colorful`'s base classes or rely on internal element structure and update them according to the latest API. Refer to the GitHub changelog for specific changes.
• breaking Version 0.5.0 introduced the use of Shadow DOM for the `hex-input` component. This affects how styling is applied to this specific input.
  Fix: To style the `hex-input` (or other elements within Shadow DOM), use CSS custom properties (variables) exposed by the component, or the `::part()` pseudo-element if parts are exposed. Direct global CSS selectors will not penetrate the Shadow DOM boundary.
• gotcha The library uses ES Modules and 'bare module specifiers' (e.g., `import 'vanilla-colorful';`). In browsers without `import maps` support, you will need a build tool (like Vite, Rollup, webpack) or a CDN with a module resolver (e.g., unpkg.com with `?module`) to resolve these imports.
  Fix: For development without a bundler, ensure your HTML script tags use `type="module"` and either configure import maps or use a CDN URL that provides module resolution: `<script type="module" src="https://unpkg.com/vanilla-colorful?module"></script>`.
• gotcha As a Custom Elements-based library, `vanilla-colorful` relies on modern browser support for Web Components. Older browsers (e.g., Internet Explorer) are not supported without polyfills.
  Fix: Ensure your target browsers have native Web Components support or include appropriate polyfills if wider browser compatibility is required. The library is designed for evergreen browsers.
• gotcha Event listeners for color changes are dispatched as `CustomEvent` with the name `color-changed`. The updated color value is available in `event.detail.value`. Frameworks often have their own syntax for listening to custom events.
  Fix: Always use `addEventListener('color-changed', ...)` in vanilla JS. When integrating with frameworks, use their specific event binding syntax (e.g., `(color-changed)="handler"` in Angular/Lit, or consider solutions like `@lit/react` for React). Avoid assuming `onChange` or other framework-specific event names.

Install

• npm install vanilla-colorful npm
• yarn add vanilla-colorful yarn
• pnpm add vanilla-colorful pnpm

Imports

• Side-effect import for custom element registration
  wrong:

  const vanillaColorful = require('vanilla-colorful');

  correct:

  import 'vanilla-colorful';

  This import registers all available color picker custom elements (e.g., `<hex-color-picker>`, `<rgb-color-picker>`). The package is ESM-only and requires `type="module"` in script tags or a bundler for bare module specifiers.
• HexColorPicker class
  wrong:

  import HexColorPicker from 'vanilla-colorful';

  correct:

  import { HexColorPicker } from 'vanilla-colorful';

  While common usage is via custom HTML elements, you can import specific picker classes if you need programmatic access, to extend them, or create custom picker components with different tag names.
• ColorChangeEvent type

  import type { ColorChangeEvent } from 'vanilla-colorful';

  For TypeScript users, this type defines the structure of the `detail` object for the `color-changed` custom event, allowing for strong typing of event handlers. Other color types like `HslColor` are also available.

Quickstart

This quickstart demonstrates how to integrate and interact with `hex-color-picker` using standard Custom Elements. It registers the component, initializes its value, listens for `color-changed` events, and updates an output element. It also shows programmatic color setting.

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Vanilla Colorful Quickstart</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
      display: flex;
      flex-direction: column;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      margin: 0;
      background-color: #f0f0f0;
    }
    .wrapper {
      display: flex;
      flex-direction: column;
      align-items: center;
      gap: 20px;
    }
    output {
      display: block;
      margin-top: 10px;
      font-size: 1.5rem;
      font-weight: bold;
      text-align: center;
      padding: 10px 20px;
      border-radius: 5px;
      border: 1px solid #ddd;
      background-color: white;
    }
  </style>
  <script type="module" src="./main.js"></script>
</head>
<body>
  <div class="wrapper">
    <h1>Choose a Color</h1>
    <hex-color-picker class="my-picker" color="#1e88e5"></hex-color-picker>
    <output id="colorOutput"></output>
  </div>
</body>
</html>

// main.js
import 'vanilla-colorful';

document.addEventListener('DOMContentLoaded', () => {
  const picker = document.querySelector('hex-color-picker.my-picker');
  const output = document.getElementById('colorOutput');

  // Set initial color output
  if (picker && output) {
    output.textContent = picker.color;
    output.style.color = picker.color; // For text color visualization
  }

  // Listen for color changes
  picker?.addEventListener('color-changed', (event) => {
    const newColor = event.detail.value;
    if (output) {
      output.textContent = newColor;
      output.style.color = newColor; // Update text color
      console.log('Color changed to:', newColor);
    }
  });

  // Example of programmatically changing the color after some time
  setTimeout(() => {
    if (picker) {
      picker.color = '#ff4500'; // Set new color (e.g., OrangeRed)
      console.log('Programmatically set color to:', picker.color);
    }
  }, 3000);
});