Copiar y Pegar con Clipboard en JavaScript
Copia y pega texto, HTML e imágenes en JavaScript con la Clipboard API: reglas de contexto seguro, fallback con execCommand y quirks reales de cada navegador
Visión General
Toda documentación y todo dashboard acaba necesitando un botón “Copiar”, y la Async Clipboard API (navigator.clipboard) es lo que lo hace posible sin plugins ni trucos con Flash oculto. El problema: la API solo funciona en contextos seguros, cada navegador impone un modelo de permisos distinto, y document.execCommand("copy") —deprecado pero todavía la única opción en motores antiguos— exige un hack con selección. Esta recipe cubre copiar y leer texto, pegar contenido rico con ClipboardItem, interceptar eventos de pegado y el fallback con execCommand que sigue haciendo falta en 2026.
Cuándo Usar
- Necesitas un botón “Copiar al portapapeles” para snippets de código, URLs para compartir o tokens de API
- Quieres leer contenido del portapapeles, por ejemplo un botón “Pegar” que pre-rellene un formulario
- Estás construyendo un editor de texto rico que debe sanitizar o transformar HTML pegado
- Necesitas soporte de portapapeles en navegadores modernos más un fallback para los antiguos
Sáltate el fallback por completo si tu audiencia usa solo navegadores modernos bajo HTTPS — en ese caso navigator.clipboard.writeText() por sí solo es suficiente.
Solución
Los snippets están listos para copiar; hay una demo ejecutable en el repositorio companion.
Copiar al portapapeles básico
async function copyToClipboard(text) {
try {
await navigator.clipboard.writeText(text);
console.log("Copied to clipboard");
return true;
} catch (err) {
console.error("Failed to copy:", err);
return false;
}
}
// Uso
document.getElementById("copy-btn").addEventListener("click", () => {
copyToClipboard("https://example.com/share-link");
});
Copiar con fallback para navegadores antiguos
async function copyToClipboard(text) {
if (navigator.clipboard && window.isSecureContext) {
try {
await navigator.clipboard.writeText(text);
return true;
} catch (err) {
// Caer al fallback
}
}
// Fallback: execCommand
const textarea = document.createElement("textarea");
textarea.value = text;
textarea.style.position = "fixed";
textarea.style.left = "-9999px";
document.body.appendChild(textarea);
textarea.focus();
textarea.select();
try {
const success = document.execCommand("copy");
document.body.removeChild(textarea);
return success;
} catch (err) {
document.body.removeChild(textarea);
return false;
}
}
// Uso
const button = document.querySelector("#copy-btn");
button.addEventListener("click", async () => {
const ok = await copyToClipboard("text to copy");
if (ok) {
button.textContent = "Copied!";
setTimeout(() => button.textContent = "Copy", 2000);
}
});
Leer texto del portapapeles
async function readClipboard() {
try {
const text = await navigator.clipboard.readText();
console.log("Clipboard content:", text);
return text;
} catch (err) {
console.error("Failed to read clipboard:", err);
return null;
}
}
// Uso: leer portapapeles al hacer click (requiere gesto del usuario)
document.getElementById("paste-btn").addEventListener("click", async () => {
const text = await readClipboard();
if (text) {
document.getElementById("output").value = text;
}
});
En Firefox y Safari, readText() no lanza un diálogo de permisos — abre un menú contextual efímero de “Pegar” que el usuario debe clicar. Chrome, en cambio, solicita el permiso clipboard-read.
Leer contenido rico (HTML, imágenes)
readText() solo devuelve texto plano. Para HTML o imágenes, usa navigator.clipboard.read(), que devuelve objetos ClipboardItem con los tipos MIME disponibles:
async function readRichClipboard() {
const items = await navigator.clipboard.read();
for (const item of items) {
console.log("Available types:", item.types); // ej. ["text/plain", "text/html", "image/png"]
if (item.types.includes("text/html")) {
const blob = await item.getType("text/html");
const html = await blob.text();
document.getElementById("editor").innerHTML = sanitizeHtml(html);
} else if (item.types.includes("image/png")) {
const blob = await item.getType("image/png");
const url = URL.createObjectURL(blob);
document.getElementById("preview").src = url;
}
}
}
Inspecciona siempre item.types primero — el portapapeles puede contener formatos que tu código no maneja, y llamar getType() sobre un tipo ausente lanza error. Sanitiza el text/html antes de inyectarlo (ver Sanitizar Entrada de Usuario para Prevenir XSS): el markup pegado desde Word o páginas web suele traer scripts y estilos inline que no quieres.
Interceptar eventos de pegado
document.getElementById("editor").addEventListener("paste", (event) => {
event.preventDefault();
const clipboardData = event.clipboardData || window.clipboardData;
const pastedText = clipboardData.getData("text/plain");
// Sanitizar o transformar el contenido pegado
const cleanText = pastedText
.replace(/<[^>]*>/g, "")
.replace(/\s+/g, " ")
.trim();
document.execCommand("insertText", false, cleanText);
});
// Manejar pegado de imágenes
document.getElementById("image-editor").addEventListener("paste", (event) => {
const items = event.clipboardData?.items;
if (!items) return;
for (const item of items) {
if (item.type.startsWith("image/")) {
const file = item.getAsFile();
const reader = new FileReader();
reader.onload = (e) => {
const img = document.createElement("img");
img.src = e.target.result;
document.getElementById("preview").appendChild(img);
};
reader.readAsDataURL(file);
}
}
});
Para inputs de archivos que aceptan tanto drag-and-drop como pegado, la misma API DataTransferItem maneja ambos flujos — ver Subida de Archivos con Drag and Drop en JavaScript.
Botón de copiar para bloques de código
function addCopyButtons() {
const codeBlocks = document.querySelectorAll("pre code");
codeBlocks.forEach((codeBlock) => {
const button = document.createElement("button");
button.className = "copy-btn";
button.textContent = "Copy";
button.style.position = "absolute";
button.style.top = "8px";
button.style.right = "8px";
button.addEventListener("click", async () => {
const text = codeBlock.textContent;
const ok = await copyToClipboard(text);
if (ok) {
button.textContent = "Copied!";
setTimeout(() => button.textContent = "Copy", 2000);
}
});
const pre = codeBlock.parentElement;
pre.style.position = "relative";
pre.appendChild(button);
});
}
addCopyButtons();
Verificar permisos del portapapeles
Los nombres clipboard-read y clipboard-write de la Permissions API son una característica solo de Chromium — Firefox y Safari no los soportan, así que query() lanza error y conviene tratarlo como “intenta la operación de todos modos”:
async function checkClipboardPermission() {
try {
const permission = await navigator.permissions.query({
name: "clipboard-write"
});
if (permission.state === "granted") {
return true;
}
if (permission.state === "prompt") {
// Preguntará en la próxima operación del portapapeles
return null;
}
return false;
} catch (err) {
// Firefox/Safari: nombre de permiso no soportado, asumir disponible
return true;
}
}
// Uso
const canCopy = await checkClipboardPermission();
if (canCopy === false) {
showNotification("Clipboard access denied. Please enable it in browser settings.");
}
Explicación
La API se divide en dos superficies. navigator.clipboard expone métodos asíncronos — writeText() y readText() para texto plano, write() y read() para tipos MIME arbitrarios envueltos en ClipboardItem. Por separado, los eventos cut/copy/paste se disparan en elementos focusable y dan acceso a event.clipboardData para inspeccionar o sobreescribir la operación. Un evento más reciente, clipboardchange sobre el objeto Clipboard, notifica cuando cambia el contenido del portapapeles del sistema — útil para apps que sincronizan un portapapeles interno propio.
Tres restricciones deciden si una llamada funciona:
- Contexto seguro:
navigator.clipboardsolo existe en HTTPS olocalhost. En HTTP plano la propiedad esundefined, así quewindow.isSecureContextes el guard que quieres antes de caer al fallback — que además es la razón por la que producción necesita TLS (ver Configurar Certificados SSL). - Activación transitoria del usuario: las escrituras deben ser disparadas por una acción del usuario en todos los motores. Chrome además persiste el permiso
clipboard-writeuna vez concedido, así que llamadas posteriores no necesitan gesto. - Divergencia del modelo de permisos: aquí nacen la mayoría de bugs tipo “funciona en Chrome, falla en otro lado”. Chromium pide
clipboard-readen la primera lectura. Firefox y Safari no implementan los nombres de permisoclipboard-read/clipboard-write— en su lugar, una lectura dentro de un gesto del usuario abre un menú contextual efímero de “Pegar” (habilitado tras ~1 segundo) que solo tiene éxito si el usuario lo clica.
Dos casos límite más que conviene conocer:
- Iframes: una página enmarcada no puede tocar el portapapeles salvo que el embebedor lo delegue — el iframe necesita
allow="clipboard-read; clipboard-write"(y el headerPermissions-Policycorrespondiente). Sin eso, las llamadas rechazan conNotAllowedError. - Promesas rechazadas: cada método del portapapeles devuelve una promesa que rechaza con un
DOMException—NotAllowedErrorpor problemas de permiso/gesto,SecurityErrorpor violaciones de contexto. Un rechazo no manejado es un fallo silencioso: el botón no hace nada y el usuario copia a mano.
El fallback document.execCommand("copy") está deprecado pero aún cubre WebViews legacy y motores anteriores a 2020. Necesita un elemento real seleccionable — el truco del textarea off-screen — y solo funciona de forma síncrona dentro del mismo gesto de usuario que lo disparó.
Variantes
| Método | Soporte | Async | Usar Cuando |
|---|---|---|---|
navigator.clipboard.writeText | Navegadores modernos | Sí | Opción por defecto, solo HTTPS |
document.execCommand("copy") | Todos los navegadores | No | Fallback para motores legacy |
navigator.clipboard.readText | Navegadores modernos | Sí | Pegar texto plano (el prompt varía por motor) |
navigator.clipboard.read / write | Chrome, Edge, Safari | Sí | HTML, imágenes, tipos MIME personalizados |
Handler de evento paste | Todos los navegadores | No | Sanitizar o transformar lo pegado |
Mejores Prácticas
- Intenta siempre
navigator.clipboardprimero y manténexecCommandcomo fallback, protegido porwindow.isSecureContext. - Da feedback visual tras copiar — cambia la etiqueta a “¡Copiado!” o voltea un icono durante ~2 segundos. Sin eso, los usuarios hacen doble click y culpan al botón.
- Maneja la promesa rechazada en cada llamada; un permiso denegado debe mostrar un mensaje, no silencio.
- Sanitiza el HTML pegado antes de que llegue al DOM — el markup crudo de otras apps es un vector de XSS.
- Lee el portapapeles solo dentro de un gesto del usuario. En Firefox y Safari la lectura se convierte literalmente en un segundo click sobre un prompt de “Pegar”, así que diseña tu UX alrededor de ese paso extra.
- Prueba en un teléfono real: iOS Safari y los WebViews de Android tienen quirks propios con
execCommandy el foco.
Errores Comunes
- Llamar a
navigator.clipboarden HTTP — la propiedad no existe fuera de contextos seguros, así que compruebawindow.isSecureContextprimero. - No manejar la promesa rechazada — la causa más común de “el botón de copiar no hace nada” es un permiso denegado o un gesto de usuario ausente.
- Olvidar remover el textarea off-screen en el fallback — cada copia fallida deja un nodo DOM fugado.
- Asumir que
readText()muestra el prompt de Chrome — en Firefox y Safari el usuario ve un menú de “Pegar” en vez de un diálogo de permisos, y espera su click en silencio. - Embeber tu app sin
allow="clipboard-*"— las llamadas al portapapeles dentro del iframe rechazan aunque el mismo código funcione a nivel top. - Inyectar
clipboardData.getData("text/html")directo eninnerHTML— te llevas los scripts y estilos inline que la app de origen copió.
Solución de Problemas
- Copiar funciona en
localhostpero falla en una IP de LAN (192.168.x.x): el origen LAN no es un contexto seguro. Prueba con HTTPS, un túnel (ngrok, cloudflared) o mantén el fallback para ese entorno. - El botón copia una vez y luego deja de funcionar en Chrome: busca un rechazo no manejado de una llamada previa — revisa
chrome://settings/content/clipboardpara ver siclipboard-writequedó denegado. readText()se queda colgado en Firefox o Safari: esperado — el navegador está mostrando el menú efímero de “Pegar” y la promesa queda pendiente hasta que el usuario lo clica.read()devuelve un item perogetType()lanza error: el portapapeles contiene formatos que no comprobaste. Lee siempreitem.typesprimero; las imágenes copiadas desde algunas apps llegan comoimage/pngmientras otras solo ofrecentext/htmlcon un<img>inline.- La consulta de permisos lanza error:
clipboard-read/clipboard-writeno están soportados pornavigator.permissionsfuera de Chromium. Trata unquery()que lanza como “desconocido” e intenta la operación dentro de un gesto del usuario.
Lectura Adicional
- MDN — Clipboard API: referencia de las interfaces y desglose por motor del comportamiento de permisos.
- MDN — ClipboardItem: tipos MIME,
getType()y notas de soporte. - caniuse — Async Clipboard API: matriz de soporte actual de
read,writey los helpers de texto. - W3C — Clipboard API and events: la especificación, incluidos los requisitos de contexto seguro y activación de usuario.
Preguntas frecuentes
¿Por qué navigator.clipboard no funciona en localhost con HTTP?
La Clipboard API requiere un contexto seguro. localhost se considera seguro incluso sobre HTTP, pero otros orígenes HTTP no — por eso falla en IPs de LAN y servidores de staging. Usa HTTPS en producción o prueba en localhost.
¿Cómo copio texto rico o HTML al portapapeles?
Usa navigator.clipboard.write() con un ClipboardItem:
const htmlBlob = new Blob(["<b>Bold text</b>"], { type: "text/html" });
const textBlob = new Blob(["Bold text"], { type: "text/plain" });
await navigator.clipboard.write([
new ClipboardItem({
"text/html": htmlBlob,
"text/plain": textBlob
})
]);
Incluye siempre un fallback text/plain para que las apps que no renderizan HTML reciban algo igualmente.
¿Puedo copiar sin un click de botón?
No de forma fiable. Todos los motores exigen activación transitoria del usuario para escribir, y Chrome solo se salta el gesto cuando el permiso clipboard-write ya fue concedido. Copiar al cargar la página o dentro de un setTimeout sin interacción previa rechazará.
¿Por qué falla el acceso al portapapeles dentro de un iframe?
El iframe necesita delegación explícita: allow="clipboard-read; clipboard-write" en la etiqueta, más un header Permissions-Policy si el embebedor lo restringe. Sin delegación las llamadas rechazan con NotAllowedError aunque funcionen a nivel top.
¿Cómo copio una imagen al portapapeles?
Usa navigator.clipboard.write() con un blob PNG:
const response = await fetch("image.png");
const blob = await response.blob();
await navigator.clipboard.write([
new ClipboardItem({ "image/png": blob })
]);
Safari solo acepta image/png para escritura de imágenes; Chrome soporta más tipos.
Recursos Relacionados
Sanitizar Input de Usuario
Cómo sanitizar y validar input de usuario en Python, Java y JavaScript para prevenir ataques de inyección.
RecipeConfigurar Certificados SSL con Let's Encrypt
Guía paso a paso para obtener certificados TLS gratuitos de Let's Encrypt con Certbot — en Nginx, Apache, standalone, Docker y Kubernetes.
RecipeSubida de Archivos Drag and Drop en JavaScript con HTML5
Implementa subida de archivos drag and drop nativa con HTML5 en JavaScript: zona de arrastre, validación, barra de progreso y vistas previas.
RecipeLocalStorage con Expiración TTL en JavaScript
Almacena datos en localStorage con expiración TTL: limpieza perezosa, manejo de cuota, stale-while-revalidate y sincronización entre pestañas
RecipeConstruir notificaciones en tiempo real con WebSockets
Implementa un sistema de notificaciones en tiempo real usando WebSockets y Redis pub/sub para difundir mensajes entre clientes.
GuideContent Security Policy: cabeceras CSP, nonces, hashes
Desplegá Content Security Policy sin romper tu sitio: directivas CSP, nonces, hashes, strict-dynamic, reportes e integración por framework.