EyeDropper API Polyfill

Common errors

• ReferenceError: EyeDropper is not defined

  cause 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

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

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

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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`.
  Fix: Add `"eyedropper-polyfill"` to the `types` array in your `tsconfig.json` under `compilerOptions` to include the global type definitions provided by the package.

Install

• npm install eyedropper-polyfill npm
• yarn add eyedropper-polyfill yarn
• pnpm add eyedropper-polyfill pnpm

Imports

• Side-effect import
  wrong:

  import { EyeDropperPolyfill } from 'eyedropper-polyfill';

  correct:

  import '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
  wrong:

  const eyedropper = new EyeDropper();

  correct:

  const eyedropper = new window.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.

Quickstart

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