{"id":16811,"library":"eyedropper-polyfill","title":"EyeDropper API Polyfill","description":"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.","status":"active","version":"1.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/iam-medvedev/eyedropper-polyfill","tags":["javascript","eyedropper","polyfill","colorpicker","typescript"],"install":[{"cmd":"npm install eyedropper-polyfill","lang":"bash","label":"npm"},{"cmd":"yarn add eyedropper-polyfill","lang":"bash","label":"yarn"},{"cmd":"pnpm add eyedropper-polyfill","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { EyeDropperPolyfill } from 'eyedropper-polyfill';","symbol":"Side-effect import","correct":"import 'eyedropper-polyfill';"},{"note":"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`.","wrong":"const eyedropper = new EyeDropper();","symbol":"Window.EyeDropper","correct":"const eyedropper = new window.EyeDropper();"},{"note":"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.","symbol":"TypeScript types","correct":"// tsconfig.json\n{\n  \"compilerOptions\": {\n    \"types\": [\"eyedropper-polyfill\"]\n  }\n}"}],"quickstart":{"code":"import 'eyedropper-polyfill';\n\nconst openEyeDropper = async () => {\n  if (!window.EyeDropper) {\n    console.error('EyeDropper API or polyfill not available.');\n    alert('Your browser does not support the EyeDropper API.');\n    return;\n  }\n\n  const eyeDropper = new window.EyeDropper();\n  const abortController = new window.AbortController();\n  const signal = abortController.signal;\n\n  // Optionally abort after 10 seconds\n  const timeoutId = setTimeout(() => {\n    console.log('EyeDropper operation timed out, aborting.');\n    abortController.abort();\n  }, 10000);\n\n  try {\n    const colorSelectionResult = await eyeDropper.open({ signal });\n    clearTimeout(timeoutId);\n    console.log('Selected color:', colorSelectionResult.sRGBHex);\n    document.body.style.backgroundColor = colorSelectionResult.sRGBHex;\n    alert(`Selected color: ${colorSelectionResult.sRGBHex}`);\n  } catch (error) {\n    clearTimeout(timeoutId);\n    if (error.name === 'AbortError') {\n      console.log('EyeDropper operation was aborted.');\n    } else {\n      console.error('Error opening EyeDropper:', error);\n    }\n  }\n};\n\n// Attach to a button click or call directly\n// Example: create a button and call this function\nconst button = document.createElement('button');\nbutton.textContent = 'Pick a color';\nbutton.style.padding = '10px 20px';\nbutton.style.fontSize = '18px';\nbutton.style.margin = '20px';\nbutton.onclick = openEyeDropper;\ndocument.body.appendChild(button);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"As 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `\"eyedropper-polyfill\"` to the `types` array in your `tsconfig.json` under `compilerOptions` to include the global type definitions provided by the package.","message":"For 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`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`).","cause":"The `eyedropper-polyfill` package was not imported, or its side-effect import did not execute before `window.EyeDropper` was accessed.","error":"ReferenceError: EyeDropper is not defined"},{"fix":"Always instantiate the EyeDropper using `new window.EyeDropper()`. Verify the polyfill has been imported correctly if `window.EyeDropper` remains undefined.","cause":"Attempting to instantiate `EyeDropper` directly (e.g., `new EyeDropper()`) instead of accessing it via the `window` object, or `window.EyeDropper` is truly undefined.","error":"TypeError: Cannot read properties of undefined (reading 'open') at new EyeDropper"},{"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.","cause":"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).","error":"DOMException: The user aborted a request."}],"ecosystem":"npm","meta_description":null}