StackPractices
beginner Por Mathias Paulenko

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

Temas: frontend

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.

Flujo de decisión para copiar: un gesto del usuario dispara la comprobación de contexto seguro y navigator.clipboard; si está disponible llama a writeText, si no cae al fallback de textarea oculto con execCommand, y después muestra feedback

Tres restricciones deciden si una llamada funciona:

  • Contexto seguro: navigator.clipboard solo existe en HTTPS o localhost. En HTTP plano la propiedad es undefined, así que window.isSecureContext es 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-write una 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-read en la primera lectura. Firefox y Safari no implementan los nombres de permiso clipboard-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 header Permissions-Policy correspondiente). Sin eso, las llamadas rechazan con NotAllowedError.
  • Promesas rechazadas: cada método del portapapeles devuelve una promesa que rechaza con un DOMException — NotAllowedError por problemas de permiso/gesto, SecurityError por 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étodoSoporteAsyncUsar Cuando
navigator.clipboard.writeTextNavegadores modernosSíOpción por defecto, solo HTTPS
document.execCommand("copy")Todos los navegadoresNoFallback para motores legacy
navigator.clipboard.readTextNavegadores modernosSíPegar texto plano (el prompt varía por motor)
navigator.clipboard.read / writeChrome, Edge, SafariSíHTML, imágenes, tipos MIME personalizados
Handler de evento pasteTodos los navegadoresNoSanitizar o transformar lo pegado

Mejores Prácticas

  • Intenta siempre navigator.clipboard primero y mantén execCommand como fallback, protegido por window.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 execCommand y el foco.

Errores Comunes

  • Llamar a navigator.clipboard en HTTP — la propiedad no existe fuera de contextos seguros, así que comprueba window.isSecureContext primero.
  • 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 en innerHTML — te llevas los scripts y estilos inline que la app de origen copió.

Solución de Problemas

  • Copiar funciona en localhost pero 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/clipboard para ver si clipboard-write quedó 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 pero getType() lanza error: el portapapeles contiene formatos que no comprobaste. Lee siempre item.types primero; las imágenes copiadas desde algunas apps llegan como image/png mientras otras solo ofrecen text/html con un <img> inline.
  • La consulta de permisos lanza error: clipboard-read/clipboard-write no están soportados por navigator.permissions fuera de Chromium. Trata un query() que lanza como “desconocido” e intenta la operación dentro de un gesto del usuario.

Lectura Adicional

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.