Índice de contenido
- ¿Qué significa copiar al portapapeles en JavaScript?
- Usando navigator.clipboard.writeText(): el método moderno
- ¿Por qué devuelve una promesa?
- Versión con async/await: código más limpio
- Consideraciones de seguridad: HTTPS y permisos del navegador
- Compatibilidad con navegadores
- Mejorando la experiencia de usuario (UX)
- Errores comunes y cómo solucionarlos
- Preguntas frecuentes (FAQ)
- Conclusión
- Método heredado: copiar al portapapeles con document.execCommand('copy')
- Leyendo imágenes del portapapeles con JavaScript: el evento paste
- 1.0 Capturando la pantalla de un ordenador
-
2.0 Guardando la captura de pantalla en un elemento
con JavaScript
- 2.1 El evento paste en JavaScript
- 2.2 Definiendo nuestra función para capturar el evento
- 2.3 Explicando la función anterior…
- ClipboardEvent.clipboardData: leyendo los datos del portapapeles
- 2.4 Resultado final del experimento
- 3. Enviando la imagen copiada del clipboard al servidor con Ajax
- 3.1 Guardando la imagen en el servidor
- 3.2 Generando un string codificado en base64 de la imagen
- El objeto FileReader()
- 3.3 ¿Cómo guardar la imagen en base64 en nuestra base de datos?
- Consideraciones importantes
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://localhosttambién está permitido, pero un virtual host conhttp://(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 nullo 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
clicko unkeydown. 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
| Error | Causa probable | Solución |
|---|---|---|
navigator.clipboard is undefined | Página sin HTTPS o contexto no seguro | Usa HTTPS o localhost |
| Promesa rechazada (permiso denegado) | Permiso denegado o bloqueo del navegador | Reintentar tras interacción directa del usuario |
| Nada se copia / sin error visible | Código ejecutado fuera de un evento de usuario | Ejecuta dentro de un click o input |
navigator.clipboard is null | Entorno 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.clipboardno funciona en HTTP?- Porque los navegadores solo habilitan la Clipboard API en sitios con
HTTPSo enlocalhost. Esto es una medida de seguridad para evitar que scripts maliciosos accedan al portapapeles del usuario sin consentimiento.
- Porque los navegadores solo habilitan la Clipboard API en sitios con
- ¿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.
- Puedes usar
- ¿Qué diferencia hay entre
execCommand('copy')yclipboard.writeText()?execCommandes 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.
- Sí. La Clipboard API también ofrece
- ¿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.
- No con la Clipboard API moderna. Como alternativa de último recurso puedes usar el método heredado con
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');| Navegador | Soporte execCommand('copy') |
|---|---|
| Internet Explorer | 10+ |
| Google Chrome | 43+ |
| Firefox | 41+ |
| Opera | 29+ |
| Safari | Sin soporte |
Puedes combinar este método con un campo de texto editable, como vimos en: Secciones editables en el HTML con el atributo contenteditable.
Leyendo imágenes del portapapeles con JavaScript: el evento paste
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:
- Capturando la pantalla de un ordenador
- Guardando la captura de pantalla en un elemento con JavaScript
- Enviando la imagen copiada del clipboard al servidor con Ajax
1.0 Capturando la pantalla de un ordenador
Muchas distribuciones Linux como Fedora incluyen herramientas integradas para realizar capturas de pantalla:

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 + Ven 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
typey 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:

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.
El siguiente paso: aprende a enviar notificaciones nativas con JavaScript.