Registry / web-framework / eyedropper-polyfill

eyedropper-polyfill

library1.1.5jsnpmunverified

The `eyedropper-polyfill` package provides a robust polyfill for the W3C EyeDropper API, enabling developers to integrate a native-like color picking experience into web applications even in browsers that lack native support. Currently at stable version `1.1.5`, the library maintains a steady release cadence, primarily focusing on bug fixes and performance improvements as seen in recent patch releases in January 2026. Its key differentiator is its ability to replicate the EyeDropper functionality by leveraging `html2canvas-pro` internally, which allows it to capture colors from rendered web page content. This makes it a critical tool for ensuring consistent UX across a wider range of browsers, bridging compatibility gaps where the native API is not available, such as older browser versions or specific environments. It's designed for browser-side use and ships with TypeScript definitions for enhanced developer experience.

web-framework

npm install eyedropper-polyfill

github ↗package ↗

INSTALL

IMPORT

SIG · EYEDROPPER-POLYFIL

eyedropper-polyfill

web-frameworkjavascriptv1.1.5

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

✓ import 'eyedropper-polyfill';

✗ import { EyeDropperPolyfill } from 'eyedropper-polyfill';

This package primarily functions as a side-effect import, which populates `window.EyeDropper` if the native API is not present. There are no named exports for the polyfill class itself.

Window.EyeDropper

✓ const eyedropper = new window.EyeDropper();

✗ const eyedropper = new EyeDropper();

After importing the polyfill, the `EyeDropper` constructor becomes available on the global `window` object, aligning with the native API specification. Direct access without `window.` might lead to `ReferenceError`.

TypeScript types

✓ // tsconfig.json { "compilerOptions": { "types": ["eyedropper-polyfill"] } }

For TypeScript projects, you need to explicitly include 'eyedropper-polyfill' in your `tsconfig.json`'s `types` array to ensure global `EyeDropper` types are recognized without needing an explicit import statement in every file where `window.EyeDropper` is used.

This quickstart demonstrates how to initialize and use the EyeDropper polyfill to pick a color, including error handling for user aborts and a fallback check for API availability. It changes the background color based on selection.

import 'eyedropper-polyfill'; const openEyeDropper = async () => { if (!window.EyeDropper) { console.error('EyeDropper API or polyfill not available.'); alert('Your browser does not support the EyeDropper API.'); return; } const eyeDropper = new window.EyeDropper(); const abortController = new window.AbortController(); const signal = abortController.signal; // Optionally abort after 10 seconds const timeoutId = setTimeout(() => { console.log('EyeDropper operation timed out, aborting.'); abortController.abort(); }, 10000); try { const colorSelectionResult = await eyeDropper.open({ signal }); clearTimeout(timeoutId); console.log('Selected color:', colorSelectionResult.sRGBHex); document.body.style.backgroundColor = colorSelectionResult.sRGBHex; alert(`Selected color: ${colorSelectionResult.sRGBHex}`); } catch (error) { clearTimeout(timeoutId); if (error.name === 'AbortError') { console.log('EyeDropper operation was aborted.'); } else { console.error('Error opening EyeDropper:', error); } } }; // Attach to a button click or call directly // Example: create a button and call this function const button = document.createElement('button'); button.textContent = 'Pick a color'; button.style.padding = '10px 20px'; button.style.fontSize = '18px'; button.style.margin = '20px'; button.onclick = openEyeDropper; document.body.appendChild(button);

Debug

Known issues

gotchaThe `eyedropper-polyfill` package relies on a global side effect to make `window.EyeDropper` available. If the import statement is executed in a script that runs after other scripts attempt to use `EyeDropper`, or if it's placed in a module that is not eagerly evaluated, `window.EyeDropper` may appear undefined.

fix

Ensure `import 'eyedropper-polyfill';` is among the first statements in your application's entry point or in a script that runs early in the page load cycle.

affects: >=1.0.0

gotchaAs the polyfill is based on `html2canvas-pro`, it inherits its limitations, particularly regarding cross-origin content. You may not be able to pick colors from elements within iframes from different domains or images loaded from distinct origins due to browser security policies.

fix

Be aware of the Same-Origin Policy. For cross-origin content that you control, consider serving resources from the same origin or configuring appropriate CORS headers, though this may not resolve all `html2canvas-pro` limitations.

affects: >=1.0.0

gotchaFor TypeScript projects, simply installing the package does not automatically provide global type declarations for `window.EyeDropper`. The TypeScript compiler will report that `EyeDropper` is not found on `window`.

fix

Add `"eyedropper-polyfill"` to the `types` array in your `tsconfig.json` under `compilerOptions` to include the global type definitions provided by the package.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: EyeDropper is not defined

The `eyedropper-polyfill` package was not imported, or its side-effect import did not execute before `window.EyeDropper` was accessed.

fix

Ensure `import 'eyedropper-polyfill';` is present and runs early in your application's lifecycle, typically in your main entry file (e.g., `index.ts` or `main.js`).

TypeError: Cannot read properties of undefined (reading 'open') at new EyeDropper

Attempting to instantiate `EyeDropper` directly (e.g., `new EyeDropper()`) instead of accessing it via the `window` object, or `window.EyeDropper` is truly undefined.

fix

Always instantiate the EyeDropper using `new window.EyeDropper()`. Verify the polyfill has been imported correctly if `window.EyeDropper` remains undefined.

DOMException: The user aborted a request.

The `open()` method of `EyeDropper` was called with an `AbortSignal`, and `abortController.abort()` was subsequently invoked (either programmatically or by user action if supported by native API).

fix

This is expected behavior for abortion. Handle this error case in your `catch` block by checking `error.name === 'AbortError'` to differentiate from other potential errors.

Upgrade

Version history

1.1.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/iam-medvedev/eyedropper-polyfill ↗

packagehttps://www.npmjs.com/package/eyedropper-polyfill ↗