Behind a Single "Paste" Button: The Tale of Two Completely Different APIs

Image2 — Sun, 05 Jul 2026 18:30:58 +0000

I used to think that adding a "paste image" feature to an upload component would be a one-liner. But when I tried to support both Ctrl+V and a clickable "Paste Button," I realized I was actually dealing with two fundamentally different browser APIs.

The Passive Approach: `clipboardData` (The `paste` Event)

When a user presses Ctrl+V, the browser fires a paste event, and the data is packed inside event.clipboardData:

const handlePaste = (event: React.ClipboardEvent) => {
  const files = Array.from(event.clipboardData?.items || [])
    .filter((it) => it.kind === 'file' && it.type.startsWith('image/'))
    .map((it) => it.getAsFile())
    .filter(Boolean) as File[];

  if (files.length) handleFiles(files);
};

The Upside: It requires no permissions and has universal browser support. Because the user explicitly initiates the paste, the browser trusts the action.

The Active Approach: `navigator.clipboard.read()` (Button Triggered)

Clicking a button to read the clipboard is a whole different story. The user didn't press Ctrl+V; instead, your code is actively trying to read their data:

const items = await navigator.clipboard.read();
for (const item of items) {
  const type = item.types.find((t) => t.startsWith('image/'));
  if (type) {
    const blob = await item.getType(type);
    handleFiles([new File([blob], `pasted.${type.split('/')[1]}`, { type })]);
  }
}

The Catch: It prompts the user for permission on the first try, and Firefox has poor support for read() when handling images. These aren't just two ways to write the same feature—they are two completely separate paths.

Feature	`clipboardData` (`Ctrl+V`)	`clipboard.read()` (Button)
Permission Prompt	None	Required
Browser Compatibility	Fully supported	Poor image support in Firefox
Focus Requirement	Required (see below)	Not required

The Sneakiest Trap: The Focus Pitfall

Developers usually bind onPaste to a specific UI element. However, DOM elements don't receive paste events by default unless they are focusable and currently focused. So, many people end up writing this:

<div tabIndex={0} onPaste={handlePaste}>...</div>

It looks fine on paper, but it's a ticking time bomb: Ctrl+V will only work after the user explicitly clicks this div to give it focus. In reality, when a user takes a screenshot and switches back to your page, the focus is almost never on the upload box. The paste silently fails, and the user feels cheated by a feature that "doesn't work".

The correct approach is to listen to the entire window so you can catch the paste event from anywhere on the page:

useEffect(() => {
  if (!enableWindowPaste) return; // Prevent multiple upload boxes from fighting over the event

  const onPaste = (e: ClipboardEvent) => { /* Extract files as shown above */ };
  window.addEventListener('paste', onPaste);

  return () => window.removeEventListener('paste', onPaste);
}, [enableWindowPaste, items.length]);

We polished all these edge cases into the upload component for Image2. The takeaway is simple: "Pasting" isn't a single feature; it's a combination of two APIs and a focus model. If you want it to be bulletproof, you need to know exactly which path you are taking.

This post isn't really about the technical nitty-gritty, though. It’s about something I find much more interesting: What it's actually like to polish a feature alongside an AI.

It all started with a vague request: "We support Ctrl+V upload now, but users don't know it exists. Help me brainstorm some solutions." What followed wasn't just a "one-shot code generation"—it was a genuine back-and-forth conversation.

It asked questions instead of rushing to code. When I suggested adding a paste button, it didn't just blindly implement it. Instead, it laid out the fact that buttons and hotkeys use entirely different clipboard APIs. It mapped out the trade-offs regarding permissions, browser compatibility, and focus requirements, and then asked: "Are you okay with the permission prompt?" It left the executive decision to me rather than making assumptions.
It caught the blind spots I didn't even think to ask about. While reviewing the code, it spotted the "focus trap"—the fact that Ctrl+V would fail unless the upload box was focused. This was completely absent from my requirements because I hadn't realized it was an issue. The true value of a great programming partner is seeing what lies outside your own peripheral vision.
It used multiple-choice options perfectly. When we were debating where to place the button, it didn't choose for me. It presented three different layout strategies, complete with text-based mockups, and let me pick. I chose "to the right of the header section," and only then did it write the implementation. It gave guidance when needed and let me steer when appropriate.
It knew how to tie up loose ends. Once the core functionality was working, it didn't stop there. It went ahead and added internationalization (i18n), accessible tooltips, and even proactively verified the aria-label tags for several icon buttons—the exact kind of polish I usually forget about.

After four rounds of iteration, my biggest takeaway is this: the value of an AI partner isn't just "speed." It’s how it forces a small feature to expose the depth it truly deserves. Focus models, API compromises, component communication, i18n, accessibility—we didn't miss a thing. It didn't do the thinking for me; it helped me think the problem all the way through.

This heavily refined feature is now live in Image2's image upload component. If you're curious, feel free to try it out and let me know what you think!

DEV Community: Image2

Behind a Single "Paste" Button: The Tale of Two Completely Different APIs

The Passive Approach: clipboardData (The paste Event)

The Active Approach: navigator.clipboard.read() (Button Triggered)

The Sneakiest Trap: The Focus Pitfall

The Passive Approach: `clipboardData` (The `paste` Event)

The Active Approach: `navigator.clipboard.read()` (Button Triggered)