JavaScript EyeDropper API: Sample Colors from Screens

The EyeDropper API provides a native browser mechanism that allows web applications to sample pixel colors directly from a user’s screen, including areas outside the web browser window. This article explains how the EyeDropper API functions in JavaScript, details its core implementation and security model, and covers how to handle color selection and user cancellation effectively.

How the EyeDropper API Works

Historically, capturing colors from a screen required complex canvas workarounds, screen-capture APIs, or external extensions, which were often restricted to the current DOM. The EyeDropper API introduces a native interface (window.EyeDropper) that delegates color picking to the operating system or browser UI.

When invoked, the browser transitions the cursor into an eyedropper tool with a magnified loupe. The user can move this loupe over any visible pixel on their monitor and click to sample the color value. The API operates asynchronously and returns the selected pixel’s color in hexadecimal sRGB format.

Basic JavaScript Implementation

Using the EyeDropper API involves checking for browser support, instantiating the EyeDropper object, and calling its open() method inside an asynchronous function.

async function sampleColor() {
  // Check for browser support
  if (!('EyeDropper' in window)) {
    console.error('The EyeDropper API is not supported in this browser.');
    return;
  }

  const eyeDropper = new EyeDropper();

  try {
    // Open the color picker UI
    const result = await eyeDropper.open();
    // result returns an object: { sRGBHex: "#RRGGBB" }
    console.log(`Sampled Color: ${result.sRGBHex}`);
  } catch (error) {
    // Handle cancellation (e.g., pressing the Escape key)
    if (error.name === 'AbortError') {
      console.log('Color sampling was canceled by the user.');
    } else {
      console.error(`An error occurred: ${error}`);
    }
  }
}

Security and Privacy Architecture

Because the eyedropper can sample pixels outside the browser viewport (such as open desktop windows, sensitive documents, or other applications), the API is designed with strict security constraints:

1. Transient Activation Requirement: The open() method can only be triggered by an explicit user gesture, such as a click or keypress event. It cannot be launched automatically by background scripts.
2. User Intent and Cancellation: The user retains full control over the selection. They must explicitly click on a pixel to confirm selection or press the Escape key to abort.
3. No Pixel Stream Access: The application receives only a single hex string (sRGBHex) representing the chosen pixel. It does not gain access to a video stream, screenshot, or pixel array of the surrounding screen area.

AbortSignal Support

The open() method accepts an optional configuration object containing an AbortSignal. This allows developers to programmatically close the eyedropper mode if a specific event occurs before the user makes a selection:

const abortController = new AbortController();
const eyeDropper = new EyeDropper();

eyeDropper.open({ signal: abortController.signal })
  .then(result => console.log(result.sRGBHex))
  .catch(err => console.log('Sampling aborted programmatically or by user.'));

// Programmatically close the eyedropper after 5 seconds
setTimeout(() => {
  abortController.abort();
}, 5000);

Browser Compatibility

The EyeDropper API is supported primarily in Chromium-based desktop browsers such as Google Chrome, Microsoft Edge, and Opera. For unsupported browsers, web applications should implement a fallback, such as a standard <input type="color"> element or an in-page canvas color palette.