Client-Side Clipboard Interaction: clipboard vs clipboard-polyfill vs clipboardy vs copy-paste

Copying and pasting data programmatically seems simple, but browser security restrictions, API inconsistencies, and environment differences make it surprisingly tricky. The four packages under review each tackle this problem differently — some for browsers, some for Node.js, and one that’s past its prime. Let’s cut through the noise and see which tool fits your real-world scenario.

🖥️ Runtime Environment: Browser vs Node.js

This is the first and most critical filter. Not all clipboard packages work everywhere.

clipboard and clipboard-polyfill are browser-only. They rely on DOM APIs like document.execCommand() or navigator.clipboard and will throw errors if used in Node.js.

clipboardy is Node.js-only. It uses platform-specific commands (pbcopy/pbpaste on macOS, clip/powershell on Windows, xclip/xsel on Linux) via child processes. It cannot run in a browser.

copy-paste was also designed for Node.js, but it’s deprecated — more on that later.

💡 Rule of thumb: If your code runs in a browser tab → use clipboard or clipboard-polyfill. If it runs in a terminal or Electron main process → use clipboardy.

✂️ Basic Copy Operation: How Each Package Writes Text

Let’s look at the simplest common task: copying a string to the clipboard.

clipboard (browser)

Designed as a minimal wrapper. You create an instance tied to a DOM element (usually a button), and it handles the rest:

import ClipboardJS from 'clipboard';

// Attach to a button with data-clipboard-text
const btn = document.querySelector('#copy-btn');
const clipboard = new ClipboardJS(btn);

// Or specify text dynamically
const clipboard2 = new ClipboardJS('.btn', {
  text: () => 'Hello, clipboard!'
});

clipboard2.on('success', e => {
  console.log('Copied:', e.text);
  e.clearSelection();
});

It automatically chooses between navigator.clipboard.writeText() (modern) and document.execCommand('copy') (legacy).

clipboard-polyfill (browser)

Provides a function-based API that mimics the standard Clipboard API, with built-in polyfill logic:

import { writeText } from 'clipboard-polyfill';

async function copyToClipboard() {
  try {
    await writeText('Hello, clipboard!');
    console.log('Copied successfully');
  } catch (err) {
    console.error('Failed to copy:', err);
  }
}

// Must be called in response to a user gesture (e.g., click handler)
document.getElementById('copy-btn').addEventListener('click', copyToClipboard);

Under the hood, it handles permission requests, iframe sandboxing, and fallbacks seamlessly.

clipboardy (Node.js)

Simple promise-based API for scripts:

import { write } from 'clipboardy';

await write('Hello, clipboard!');
console.log('Text copied to system clipboard');

Works in any Node.js context — great for CLI tools that need to output something directly to the clipboard.

copy-paste (Node.js, deprecated)

Used a callback-style API:

// ⚠️ DO NOT USE — shown for reference only
const copyPaste = require('copy-paste');

copyPaste.copy('Hello, clipboard!', () => {
  console.log('Copied');
});

But this package is no longer maintained and fails on newer OS versions due to changes in clipboard utilities.

🔍 Reading from the Clipboard

Not all packages support reading clipboard content — and for good reason: browsers restrict read access for security.

• clipboard: ❌ Does not support reading. Only writing.
• clipboard-polyfill: ✅ Supports reading via readText(), but only in secure contexts (HTTPS) and only when triggered by a user gesture. Falls back gracefully where unsupported.

import { readText } from 'clipboard-polyfill';

async function readFromClipboard() {
  try {
    const text = await readText();
    console.log('Pasted:', text);
  } catch (err) {
    console.error('Read failed:', err);
  }
}

• clipboardy: ✅ Full read/write support in Node.js:

import { read, write } from 'clipboardy';

await write('test');
const content = await read(); // returns 'test'

• copy-paste: Supported reading via paste(), but again — deprecated and unreliable.

🛡️ Security and User Gesture Requirements

Browsers require clipboard write operations to occur within a user-initiated event (like a click). All browser packages respect this, but they handle violations differently.

• clipboard: Silently fails if not triggered by a user action. No error thrown in legacy mode.
• clipboard-polyfill: Throws a clear error in development if called outside a user gesture, helping catch bugs early.
• clipboardy: No such restriction in Node.js — you can read/write anytime.

Also, clipboard-polyfill properly handles the Permissions API for clipboard access in modern browsers, requesting permission when needed.

🧩 Advanced Features: HTML, Images, Custom Formats

Most apps only need plain text, but some require richer content.

• clipboard: Plain text only. No support for HTML or other formats.
• clipboard-polyfill: Supports writing HTML and custom MIME types via write():

import { write } from 'clipboard-polyfill';

const dt = new DataTransfer();
dt.setData('text/plain', 'Fallback text');
dt.setData('text/html', '<b>Bold text</b>');

await write(dt);

This aligns with the official Clipboard API spec.

• clipboardy: Plain text only. Binary or rich content isn’t supported.
• copy-paste: Plain text only (and broken).

🚫 Deprecation Warning: Avoid copy-paste

The copy-paste package has been deprecated by its author. Its last update was years ago, it uses unsafe child_process.exec calls without proper escaping, and it fails on modern systems (e.g., macOS Sonoma removed pbcopy from default PATH in some contexts). The README now recommends using clipboardy instead. Do not use copy-paste in new projects.

🧪 Real-World Decision Guide

Scenario 1: “Copy” Button in a React App

You’re building a dashboard with a button that copies an API key to the clipboard.

• ✅ Best choice: clipboard or clipboard-polyfill
• Why? Both work in browsers. If you only need plain text and want minimal bundle impact → clipboard. If you need better error handling, future-proofing, or plan to read clipboard later → clipboard-polyfill.

// With clipboard-polyfill (recommended for new apps)
import { writeText } from 'clipboard-polyfill';

function CopyButton({ text }) {
  const handleClick = () => writeText(text);
  return <button onClick={handleClick}>Copy</button>;
}

Scenario 2: CLI Tool That Copies Output to Clipboard

You’re writing a Node.js script that generates a config snippet and puts it in the clipboard.

• ✅ Best choice: clipboardy
• Why? It’s the only actively maintained, reliable option for Node.js.

#!/usr/bin/env node
import { write } from 'clipboardy';

const config = `API_KEY=${process.env.API_KEY}`;
await write(config);
console.log('Config copied to clipboard!');

Scenario 3: Enterprise Web App Supporting IE11

You must support older browsers in a corporate environment.

• ✅ Best choice: clipboard-polyfill
• Why? It includes robust fallbacks for execCommand and handles quirks in older browsers better than clipboard.

Scenario 4: Reading Pasted Content in a Rich Text Editor

You want users to paste formatted text and capture it.

• ✅ Best choice: clipboard-polyfill (for read() support)
• Note: You’ll still need to listen to paste events and extract data from event.clipboardData for full control — but readText() can help in simpler cases.

📊 Summary Table

* readText() requires user gesture and secure context.

💡 Final Recommendation

• For modern browser apps: Use clipboard-polyfill. It’s standards-aligned, handles edge cases, and prepares you for future clipboard features.
• For simple browser copy buttons with minimal footprint: clipboard is acceptable if you don’t need read access or advanced error reporting.
• For Node.js or CLI tools: clipboardy is the only sane choice.
• Never use copy-paste — it’s a relic.

Choose based on your runtime first, then your feature needs. Don’t overcomplicate it — most web apps only need to write plain text, and both clipboard and clipboard-polyfill do that well. But if you care about maintainability and forward compatibility, clipboard-polyfill is the smarter long-term bet for browser-based clipboard interaction.