Clipboard Copy Utilities: clipboard-copy vs clipboard-polyfill

Both clipboard-copy and clipboard-polyfill are lightweight npm packages designed to simplify copying text to the user's clipboard in web applications. While they share a common goal, their implementation strategies, browser support philosophies, and usage patterns differ significantly. Let’s break down how each works and where they shine.

📋 Core Approach: Minimal Wrapper vs Full Polyfill

clipboard-copy is a tiny utility that wraps the modern Clipboard API (navigator.clipboard.writeText) with minimal fallback logic. It assumes you're working in an environment where the Clipboard API is available or where graceful degradation is acceptable.

// Using clipboard-copy
import copy from 'clipboard-copy';

async function copyToClipboard(text) {
  try {
    await copy(text);
    console.log('Copied!');
  } catch (err) {
    console.error('Failed to copy', err);
  }
}

clipboard-polyfill provides a full-featured polyfill for the Clipboard API, including robust fallbacks for older browsers using hidden <textarea> elements and document.execCommand. It aims to make navigator.clipboard.writeText() work everywhere — even in environments where it’s natively unsupported.

// Using clipboard-polyfill
import { writeText } from 'clipboard-polyfill';

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

💡 Note: clipboard-polyfill also patches the global navigator.clipboard object by default (unless configured otherwise), so you can use the standard API directly after importing it.

🌐 Browser Support Strategy

clipboard-copy targets modern browsers only. It uses navigator.clipboard.writeText() and throws an error if the API isn’t available (e.g., in older browsers or insecure contexts like HTTP). It does not include any fallback mechanism.

This means:

• Works reliably in Chrome, Firefox, Safari, and Edge (all recent versions)
• Fails silently or throws in older browsers (e.g., IE11, legacy mobile browsers)
• Requires your app to be served over HTTPS (a security requirement of the Clipboard API)

clipboard-polyfill actively polyfills missing functionality. It detects whether navigator.clipboard exists and, if not, implements its own version using legacy techniques (execCommand + temporary DOM elements).

This gives you:

• Support back to IE9 (with caveats)
• Graceful operation on HTTP during development (though production should still use HTTPS)
• Consistent API regardless of browser capabilities

⚙️ Implementation Details & Side Effects

clipboard-copy has zero side effects. It doesn’t modify global objects or inject DOM elements. It simply calls the native API and returns the promise.

// Internally, clipboard-copy does roughly this:
export default async function copy(text) {
  if (!navigator.clipboard) {
    throw new Error('Clipboard API not supported');
  }
  return navigator.clipboard.writeText(text);
}

clipboard-polyfill may modify the DOM temporarily during copy operations. When falling back to execCommand, it creates a hidden <textarea>, appends it to the document, selects its content, and executes the copy command — then cleans up afterward.

It also patches navigator.clipboard by default:

// After import, this works even in old browsers:
await navigator.clipboard.writeText('hello');

If you prefer not to pollute globals, you can use the named export (writeText) instead.

🔒 Security and Context Requirements

Both libraries are subject to the same user activation requirement: clipboard writes must happen in response to a user gesture (e.g., a click). However, their behavior differs when this rule is violated.

• clipboard-copy will reject with a NotAllowedError (as per spec)
• clipboard-polyfill will also fail, but its fallback path might behave inconsistently across older browsers

Additionally, clipboard-copy requires HTTPS because the native Clipboard API blocks access on insecure origins. clipboard-polyfill’s fallback works on HTTP, which can be useful during local development — but remember that execCommand is deprecated and unreliable in many contexts.

🛠️ Error Handling and Debugging

clipboard-copy errors are straightforward: either the API isn’t supported, or the copy operation was denied. Errors map directly to browser-native exceptions.

clipboard-polyfill abstracts away browser differences, but this can make debugging harder. For example, a failure in the fallback path might manifest as a generic error rather than a clear “execCommand not allowed” message.

You can enable debug logging in clipboard-polyfill:

import { setDebugLog } from 'clipboard-polyfill';
setDebugLog(console.log);

clipboard-copy offers no such utilities — by design.

🧪 Real-World Usage Scenarios

Scenario 1: Modern Web App (React, Svelte, etc.) on HTTPS

You’re building a SaaS dashboard that only supports evergreen browsers and runs on HTTPS.

• ✅ Best choice: clipboard-copy
• Why? Smaller footprint, no polyfill overhead, and matches your target environment perfectly.

// Clean, modern, and sufficient
import copy from 'clipboard-copy';

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

Scenario 2: Public-Facing Site with Broad Browser Support

You run a documentation site that must work on older mobile browsers and during local HTTP development.

• ✅ Best choice: clipboard-polyfill
• Why? Ensures copy functionality works across the widest possible range of devices and contexts.

// Reliable everywhere
import { writeText } from 'clipboard-polyfill';

function CopySnippet({ code }) {
  const handleCopy = () => writeText(code);
  return <button onClick={handleCopy}>Copy</button>;
}

Scenario 3: Library Author Avoiding Global Pollution

You’re publishing a UI component library and don’t want to modify navigator.clipboard.

• ✅ Best choice: clipboard-polyfill (using named exports)
• Why? You get cross-browser support without side effects.

// Safe for libraries
import { writeText } from 'clipboard-polyfill';
// navigator.clipboard remains untouched

📦 Bundle Impact and Maintenance

While bundle size isn’t part of this comparison per instructions, it’s worth noting architecturally:

• clipboard-copy is ~300 bytes minified — essentially negligible
• clipboard-polyfill is larger due to fallback logic, but still under 5KB

Both packages are actively maintained as of 2024, with no deprecation notices on npm or GitHub.

🆚 Summary: Key Differences

💡 Final Recommendation

Choose clipboard-copy if:

• Your users are on modern browsers
• Your app runs on HTTPS
• You want the smallest possible dependency
• You’re okay with copy failing gracefully in unsupported environments

Choose clipboard-polyfill if:

• You need to support older browsers
• You develop locally over HTTP and want copy to work
• You prefer a consistent API across all environments
• You’re willing to accept slightly more complexity for broader reach

In practice, most new applications targeting contemporary browsers can safely use clipboard-copy. But if your audience includes users on legacy systems or constrained environments, clipboard-polyfill remains the more resilient choice.