Copiar Texto al Portapapeles con JavaScript — Clipboard API y navigator.clipboard.writeText()

- Andrés Cruz - EN In english

Video thumbnail

Copiar texto al portapapeles desde una página web puede parecer algo básico, pero detrás hay toda una API moderna y una serie de consideraciones de seguridad importantes. En esta guía te mostraré cómo implementar esta funcionalidad en JavaScript, con ejemplos reales, compatibilidad entre navegadores y algunos trucos que aprendí al aplicarlo en mis propios proyectos.

Cuando copiamos algo desde una aplicación o una web, estamos modificando el portapapeles de nuestro sistema operativo —y aquí viene un punto clave: estamos accediendo al SO directamente desde JavaScript, lo que implica permisos, contexto seguro y operaciones asíncronas.

Te mostraré cómo modificar el portapapeles e implementar la funcionalidad de copiar y pegar usando JavaScript, desde el método moderno con la Clipboard API hasta el enfoque heredado con execCommand.

Antes vimos cómo emplear el Arrastrar y Soltar en HTML y JavaScript.

¿Qué significa copiar al portapapeles en JavaScript?

Cuando copiamos algo —ya sea un texto, un enlace o un fragmento de código— estamos modificando el portapapeles del sistema operativo. Esto implica una pequeña "conversación" entre el navegador y el SO, algo que JavaScript puede hacer mediante la Clipboard API.

El portapapeles no es más que una herramienta del sistema operativo que permite almacenar temporalmente datos como textos e imágenes. Se accede a él generalmente con la combinación Ctrl + C para copiar y Ctrl + V para pegar; pero desde JavaScript podemos controlarlo programáticamente.

La primera vez que necesité esta funcionalidad fue para permitir que los usuarios copiaran fragmentos de código con un clic en mi plataforma de academia. Empecé usando document.execCommand('copy'), pero ese método está obsoleto y su comportamiento varía entre navegadores. La solución moderna, segura y recomendada hoy es navigator.clipboard.writeText().

Usando navigator.clipboard.writeText(): el método moderno

La Clipboard API ofrece una forma sencilla y segura de copiar texto al portapapeles. El método navigator.clipboard.writeText() recibe el texto que quieres copiar y devuelve una promesa, porque se trata de una operación asíncrona que interactúa directamente con el sistema operativo.

navigator.clipboard.writeText("Tu texto aquí");

¿Por qué devuelve una promesa?

Cada vez que accedemos a disco, al sistema operativo o a recursos del dispositivo desde JavaScript, se utiliza una promesa (Promise), porque esas operaciones no se resuelven de forma instantánea. El navegador necesita verificar permisos, comunicarse con el SO y esperar confirmación antes de completar la escritura.

Por eso navigator.clipboard.writeText() también es asíncrono: se resuelve cuando el texto ha sido copiado correctamente. Si quieres ejecutar algo justo después —como notificar al usuario— puedes encadenarlo con .then():

btn.addEventListener('click', () => {
  const text = pre.innerText;
  navigator.clipboard.writeText(text).then(() => {
    this.$toast.success(this.$t('resource.copied') + "!");
  }).catch(err => {
    console.error('Error al copiar: ', err);
  });
});

En el ejemplo anterior, capturo el texto del elemento pre usando innerText y, tras copiarlo exitosamente, muestro un toast de confirmación al usuario. El bloque .catch() es fundamental: sin él, los errores silenciosos pueden confundir tanto al desarrollador como al usuario.

Versión con async/await: código más limpio

Una alternativa que hace el código más legible es usar async/await con un bloque try/catch:

async function copiarTexto(texto) {
  try {
    await navigator.clipboard.writeText(texto);
    alert("Texto copiado al portapapeles ✅");
  } catch (err) {
    console.error("No se pudo copiar:", err);
  }
}

Ambas formas —.then()/.catch() y async/await— son válidas. Yo personalmente prefiero async/await cuando la lógica posterior al copiado es más extensa, ya que evita el anidamiento de callbacks.

Consideraciones de seguridad: HTTPS y permisos del navegador

La Clipboard API tiene requisitos de seguridad estrictos que debes conocer antes de implementarla:

  • Solo funciona en contextos seguros: la página debe estar servida bajo HTTPS. En desarrollo local, https://localhost también está permitido, pero un virtual host con http:// (sin la "s") no lo es.
  • Si intentas usar la API en un entorno inseguro, obtendrás un error similar a este:

    navigator.clipboard is null

    o incluso navigator.clipboard is undefined, dependiendo del navegador.

  • Debe ejecutarse dentro de un evento de usuario: los navegadores bloquean el acceso al portapapeles si la llamada no está originada por una acción directa del usuario, como un click o un keydown. Intentar copiar automáticamente al cargar la página, por ejemplo, suele fallar por esta razón.
  • La primera vez que el usuario visita la página puede que el navegador solicite confirmación explícita de permisos para acceder al portapapeles (especialmente al leer de él con clipboard.readText()).

En mi caso, la primera vez que lo probé en un entorno local con HTTP, el método simplemente no respondía. Al activar HTTPS, todo funcionó correctamente de inmediato.

Compatibilidad con navegadores

navigator.clipboard.writeText() tiene soporte en todos los navegadores modernos: Chrome, Firefox, Edge, Opera y Safari (desde la versión 13.1). La única excepción notable es Internet Explorer, que no soporta la Clipboard API moderna.

Para verificar en tiempo de ejecución si el navegador del usuario soporta la API antes de llamarla, puedes hacer esta comprobación:

if (navigator.clipboard) {
  // puedes usar navigator.clipboard.writeText()
  navigator.clipboard.writeText("Texto copiado");
} else {
  // muestra un mensaje alternativo o usa el método heredado
  console.warn("Clipboard API no soportada en este navegador.");
}

Mejorando la experiencia de usuario (UX)

Más allá de que funcione técnicamente, es importante que el usuario sepa que el texto se copió correctamente. Algunas estrategias que funcionan bien:

  • Mostrar un toast o notificación temporal de confirmación.
  • Cambiar el texto del botón de "Copiar" a "¡Copiado!" durante unos segundos.
  • Añadir un ícono de check (✅) como feedback visual inmediato.

Por ejemplo, para cambiar el texto del botón temporalmente:

async function copiarConFeedback(btn, texto) {
  try {
    await navigator.clipboard.writeText(texto);
    btn.textContent = "¡Copiado! ✅";
    setTimeout(() => { btn.textContent = "Copiar"; }, 2000);
  } catch (err) {
    console.error("Error al copiar:", err);
  }
}

También puedes disparar la copia al hacer doble clic, aunque esto debe hacerse con precaución: algunos navegadores bloquean el acceso al portapapeles si no hay una interacción directa reconocida por el motor del navegador.

Errores comunes y cómo solucionarlos

ErrorCausa probableSolución
navigator.clipboard is undefinedPágina sin HTTPS o contexto no seguroUsa HTTPS o localhost
Promesa rechazada (permiso denegado)Permiso denegado o bloqueo del navegadorReintentar tras interacción directa del usuario
Nada se copia / sin error visibleCódigo ejecutado fuera de un evento de usuarioEjecuta dentro de un click o input
navigator.clipboard is nullEntorno HTTP (sin SSL)Activa HTTPS en tu servidor o entorno local

En mi experiencia, el error más habitual es ejecutar la función antes de que el usuario interactúe. Por seguridad, la mayoría de navegadores modernos no permiten acceder al portapapeles sin una acción explícita del usuario.

Preguntas frecuentes (FAQ)

  • ¿Por qué navigator.clipboard no funciona en HTTP?
    • Porque los navegadores solo habilitan la Clipboard API en sitios con HTTPS o en localhost. Esto es una medida de seguridad para evitar que scripts maliciosos accedan al portapapeles del usuario sin consentimiento.
  • ¿Qué navegadores soportan clipboard.writeText()?
    • Chrome 66+, Firefox 63+, Edge 79+, Opera 53+ y Safari 13.1+. La gran excepción es Internet Explorer, que no tiene soporte.
  • ¿Cómo puedo mostrar un mensaje cuando el texto se copia?
    • Puedes usar alert(), un toast, cambiar el texto del botón o cualquier otro mecanismo visual. Lo más recomendable es un mensaje no intrusivo que desaparezca automáticamente.
  • ¿Qué diferencia hay entre execCommand('copy') y clipboard.writeText()?
    • execCommand es una API antigua, obsoleta y con comportamiento inconsistente entre navegadores. clipboard.writeText() es el método moderno, asíncrono, seguro y respaldado por el estándar W3C. Siempre deberías preferir la segunda.
  • ¿Puedo leer el portapapeles con JavaScript?
    • Sí. La Clipboard API también ofrece navigator.clipboard.readText() para leer el contenido del portapapeles, aunque este método requiere permiso explícito del usuario y solo funciona en HTTPS.
  • ¿Puedo copiar al portapapeles en JavaScript sin HTTPS?
    • No con la Clipboard API moderna. Como alternativa de último recurso puedes usar el método heredado con document.execCommand('copy'), aunque no es recomendable para proyectos nuevos.

Conclusión

Copiar texto al portapapeles con JavaScript es una funcionalidad pequeña, pero poderosa. Usando navigator.clipboard.writeText() puedes ofrecer una experiencia fluida, segura y completamente moderna sin dependencias externas.

En mi caso, aplicar esta técnica en la plataforma de Academia mejoró notablemente la interacción con los usuarios: implementé un botón de "Copiar código" en cada bloque de código, y la respuesta fue muy positiva. Con un solo clic, el usuario ya tiene el fragmento en su portapapeles.

A continuación te dejo también el enfoque heredado con execCommand para que lo tengas de referencia, especialmente si necesitas dar soporte a entornos antiguos.

Método heredado: copiar al portapapeles con document.execCommand('copy')

Antes de la existencia de la Clipboard API, la forma de copiar contenido al portapapeles desde JavaScript era mediante el método document.execCommand('copy'). Este método, aunque obsoleto hoy en día, sigue funcionando en muchos navegadores y puede ser útil como fallback para entornos sin HTTPS.

El truco consiste en crear un campo de texto oculto, asignarle el valor que queremos copiar, seleccionarlo programáticamente y luego ejecutar el comando de copia:

function copiar(id_elemento) {
  // Crea un campo de texto temporal
  var aux = document.createElement("input");
  // Asigna el contenido del elemento al valor del campo
  aux.setAttribute("value", document.getElementById(id_elemento).innerHTML);
  // Añade el campo al DOM
  document.body.appendChild(aux);
  // Selecciona el contenido del campo
  aux.select();
  // Ejecuta el comando de copia
  document.execCommand("copy");
  // Elimina el campo temporal del DOM
  document.body.removeChild(aux);
  console.log("texto copiado");
}

Antes de usar document.execCommand("copy"), es buena práctica verificar si el navegador lo soporta mediante:

document.queryCommandSupported('copy');
NavegadorSoporte execCommand('copy')
Internet Explorer10+
Google Chrome43+
Firefox41+
Opera29+
SafariSin soporte

Puedes combinar este método con un campo de texto editable, como vimos en: Secciones editables en el HTML con el atributo contenteditable.

Ver ejemplo

Leyendo imágenes del portapapeles con JavaScript: el evento paste

Ver ejemplo Descargar fuente

La Clipboard API no solo permite copiar texto: también podemos interceptar imágenes provenientes de una captura de pantalla que el usuario haya guardado en su portapapeles, y mostrarlas directamente en un elemento <img> de la página.

Además, veremos cómo enviar esa imagen al servidor mediante Ajax para procesarla y guardarla. A continuación, el índice de contenidos:

  1. Capturando la pantalla de un ordenador
  2. Guardando la captura de pantalla en un elemento con JavaScript
    1. El evento paste en JavaScript
    2. Definiendo nuestra función para capturar el evento
    3. Explicando la función anterior…
  3. Enviando la imagen copiada del clipboard al servidor con Ajax
    1. Guardando la imagen en el servidor
    2. Generando un string codificado en base64 de la imagen en el servidor
    3. ¿Cómo guardar la imagen en base64 en nuestra base de datos?

1.0 Capturando la pantalla de un ordenador

Muchas distribuciones Linux como Fedora incluyen herramientas integradas para realizar capturas de pantalla:

captura de pantalla aplicación

Estas herramientas permiten guardar la imagen en una ubicación del disco o directamente en el portapapeles; este último caso es el que nos interesa.

También puedes usar la tecla Impr Pant (Print Screen) disponible en muchos teclados, aunque su comportamiento varía: en algunos sistemas operativos guarda la captura en el portapapeles automáticamente, y en otros la guarda directamente en disco.

2.0 Guardando la captura de pantalla en un elemento <img> con JavaScript

Una vez que tenemos la captura en el portapapeles, debemos escuchar el momento en que el usuario la pega en la página web. Esto puede ocurrir de tres formas:

  • La combinación Ctrl + V en el teclado.
  • Seleccionando la opción "Pegar" desde el menú contextual del navegador.
  • Usando el menú emergente (clic derecho) y eligiendo la opción "Pegar".

Más información sobre el evento paste en w3schools.

2.1 El evento paste en JavaScript

JavaScript expone el evento paste que se dispara cada vez que el usuario pega contenido en la página. Podemos escucharlo a nivel global de la siguiente forma:

window.addEventListener("paste", pasteEvent);

2.2 Definiendo nuestra función para capturar el evento

Definimos la función pasteEvent() (o processEvent()) que se ejecutará cuando el usuario pegue contenido. Dentro de ella, inspeccionamos los ítems del portapapeles para identificar si hay una imagen y mostrarla en un elemento <img>:

window.addEventListener("paste", processEvent);

function processEvent(e) {
    for (var i = 0; i < e.clipboardData.items.length; i++) {
        // Obtengo el clipboard item
        var clipboardItem = e.clipboardData.items[0];
        var type = clipboardItem.type;
        // Verifico si es una imagen
        if (type.indexOf("image") != -1) {
            // Obtengo el contenido de la imagen como BLOB
            var blob = clipboardItem.getAsFile();
            console.log("blob", blob);
            // Creo una URL temporal del objeto
            var blobUrl = URL.createObjectURL(blob);
            console.log("blobUrl", blobUrl);
            // Asigno la imagen al elemento 
            document.getElementsByTagName("img")[0].setAttribute("src", blobUrl);
        } else {
            console.log("Tipo no soportado: " + type);
        }
    }
}

2.3 Explicando la función anterior…

ClipboardEvent.clipboardData: leyendo los datos del portapapeles

El objeto clipboardData permite acceder en modo solo lectura a la data contenida en el portapapeles, expuesta como un array de items. Cada ítem tiene un tipo de dato (texto, imagen, etc.) y la data en sí misma:

var clipboardItem = e.clipboardData.items[i];

Una vez que tenemos el ítem a evaluar, determinamos el tipo de dato y lo procesamos:

  • Consultamos el tipo mediante la propiedad type y buscamos si contiene "image": type.indexOf("image").
  • Obtenemos los datos BLOB (raw data) mediante el método getAsFile(): clipboardItem.getAsFile().

Una vez obtenida la data BLOB, la convertimos a una URL temporal usando URL.createObjectURL(), que crea un DOMString con una URL que representa el objeto, permitiendo que la imagen sea renderizada en el elemento <img>:

var blobUrl = URL.createObjectURL(blob);

Finalmente, asignamos esa URL como atributo src del elemento de imagen:

img.setAttribute("src", blobUrl);

2.4 Resultado final del experimento

Copia una imagen en tu portapapeles (con Ctrl + C sobre una imagen, o con Impr Pant) y luego pégala en la página con Ctrl + V. La imagen aparecerá renderizada en el elemento <img> de la página.

3. Enviando la imagen copiada del clipboard al servidor con Ajax

3.1 Guardando la imagen en el servidor

Una vez que tenemos la imagen renderizada en el elemento <img>, el siguiente paso es enviarla al servidor para procesarla y guardarla. Para esto podemos usar Ajax o un formulario tradicional. Sin embargo, antes de enviarla debemos convertirla a un formato que el servidor pueda manejar correctamente: una cadena codificada en base64.

3.2 Generando un string codificado en base64 de la imagen

Si inspeccionamos el atributo src de la imagen tras asignar la URL BLOB:

src img

Veremos que el valor es una URL tipo blob:http://..., que es una referencia temporal al objeto en memoria. Ese formato no puede enviarse directamente al servidor ni guardarse en base de datos; necesitamos convertir la imagen a base64 primero. Podemos hacerlo con la API FileReader:

var reader = new window.FileReader();
reader.readAsDataURL(clipboardItem.getAsFile());

reader.onload = function() {
    var base64Data = reader.result
        .replace('data:image/png;base64,', '')
        .toString();

    $.ajax({
        type: 'POST',
        url: URL,
        data: {
            'pantalla': base64Data,
        },
        success: function(response) {}
    });
};

El objeto FileReader()

El objeto FileReader permite leer archivos de manera asíncrona directamente desde el navegador. Al llamar a reader.readAsDataURL(), convierte el Blob en una cadena data:URL codificada en base64. Una vez completada la lectura, la propiedad reader.result contiene esa cadena lista para ser procesada.

Una vez codificada la imagen, podemos enviarla por Ajax o incluirla en un campo oculto de un formulario.

3.3 ¿Cómo guardar la imagen en base64 en nuestra base de datos?

En el lado del servidor, debemos decodificar la cadena base64 para obtener los bytes de la imagen. Si usas Java Web, puedes hacerlo con:

byte[] imagen = Base64.decodeBase64(imageString);

En PHP, la función equivalente es:

$data = base64_decode($data);

Una vez decodificada, la imagen se puede guardar en base de datos o en el sistema de archivos exactamente igual que cualquier otro archivo recibido a través de un input de tipo file.

Consideraciones importantes

Dependiendo de la función de decodificación que uses en el servidor, puede ser necesario retirar la cabecera data:image/png;base64, del string antes de decodificarlo. Esto aplica especialmente a la función Base64.decodeBase64 en Java: si no se elimina esa cabecera, la imagen se decodificará con errores y el archivo quedará corrupto.

Ver ejemplo Descargar fuente

El siguiente paso: aprende a enviar notificaciones nativas con JavaScript.

Aprende a usar navigator.clipboard.writeText() para copiar texto al portapapeles en JavaScript. Ejemplos con async/await, permisos HTTPS leer imágenes del clipboard.


Únete a la comunidad de desarrolladores que han decidido dejar de picar código y empezar a construir productos reales. Recibe mis mejores trucos de arquitectura cada semana:

Acepto recibir anuncios de interes sobre este Blog.