Registry / web-framework / vanilla-colorful

vanilla-colorful

library0.7.2jsnpmunverified

vanilla-colorful is a lightweight, framework-agnostic color picker library implemented as W3C standards-based Custom Elements. It serves as a vanilla JavaScript port of the popular `react-colorful` library, offering the same core functionality in a dependency-free, highly optimized package. The current stable version is 0.7.2, released in November 2022, and while no explicit release cadence is stated, it appears to be actively maintained. Key differentiators include its extremely small bundle size (just 2.7 KB minified and gzipped), 100% test coverage, full TypeScript typings, and comprehensive accessibility (WAI-ARIA) and mobile support. It provides various color picker types (HEX, RGB, HSL, HSV) directly usable as HTML custom elements, making integration into any web application or framework straightforward.

web-framework

npm install vanilla-colorful

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VANILLA-COLORFUL

vanilla-colorful

web-frameworkjavascriptv0.7.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Side-effect import for custom element registration

✓ import 'vanilla-colorful';

✗ const vanillaColorful = require('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

✓ import { HexColorPicker } from 'vanilla-colorful';

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

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.

<!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); });

Debug

Known issues

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

affects: >=0.7.0

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

affects: >=0.6.0

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

affects: >=0.5.0

gotchaThe 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>`.

affects: >=0.1.0

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

affects: >=0.1.0

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

affects: >=0.1.0

Errors

Common errors & fixes

Uncaught SyntaxError: Cannot use import statement outside a module

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

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

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.

Upgrade

Version history

0.7.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/web-padawan/vanilla-colorful ↗

packagehttps://www.npmjs.com/package/vanilla-colorful ↗

homepagehttps://vanilla-colorful.web.app/ ↗