Clipboard API: copiar y pegar en React

navigator.clipboard.writeText(text) escribe una cadena en el portapapeles del sistema y devuelve una Promise. Es el reemplazo moderno del enfoque heredado execCommand. Espere siempre la Promise con await y gestione un posible rechazo, por ejemplo, cuando el usuario deniega el acceso al portapapeles.

navigator.clipboard.readText() lee el contenido actual del portapapeles como una cadena y también devuelve una Promise. La lectura requiere el permiso clipboard-read, que el navegador solicita al usuario. En la práctica, la lectura del portapapeles se utiliza con menos frecuencia que la escritura en las aplicaciones React habituales.

Los navegadores exigen que clipboard.writeText solo se llame dentro de un controlador de gestos del usuario, como un evento de clic o keydown. Llamarlo dentro de un useEffect o de forma asíncrona después del gesto provocará un error de seguridad. Active siempre la escritura directamente desde un controlador onClick.

El patrón estándar es el siguiente: el usuario hace clic en un botón de copia, el controlador llama a navigator.clipboard.writeText(value), tras una operación correcta se establece el estado copied en true y el botón muestra temporalmente una marca de verificación o la etiqueta «¡Copiado!». Después de un breve intervalo, el botón vuelve a su estado normal.

Encapsule la lógica en un hook useCopyToClipboard que devuelva una tupla: [copied, copyFn]. El booleano copied controla la confirmación visual y copyFn acepta el texto que se copiará. El hook gestiona internamente la escritura asíncrona y cualquier error, para que los componentes sigan siendo sencillos.

Dentro del hook, después de copiar correctamente, establezca setCopied(true) y programe un restablecimiento con setTimeout(() => setCopied(false), 2000). Guarde el identificador del temporizador y elimínelo en la limpieza de un useEffect para evitar actualizaciones de estado después de desmontar el componente. Así se evita la advertencia «cannot update state on an unmounted component».

Los navegadores antiguos y las páginas que no utilizan HTTPS no admiten la Clipboard API. La alternativa heredada crea temporalmente un textarea, establece su valor, lo añade al body, llama a document.execCommand('copy') y elimina el elemento. Este enfoque es síncrono y funciona en todas partes, aunque está obsoleto.

Antes de utilizar la Clipboard API, compruebe lo siguiente: navigator.clipboard && typeof navigator.clipboard.writeText === 'function'. Si no está disponible, recurra al enfoque heredado de execCommand. Esta comprobación preventiva evita errores en tiempo de ejecución en entornos que no admiten la API.

La lectura del portapapeles requiere el permiso del usuario mediante la Permissions API. Puede consultar el estado actual: navigator.permissions.query({ name: 'clipboard-read' }) devuelve un PermissionStatus con un state de granted, denied o prompt. El navegador solicitará el permiso automáticamente al llamar a readText().

La Clipboard API solo está disponible en contextos seguros (HTTPS o localhost). En páginas HTTP, navigator.clipboard es undefined. Se trata de una restricción de seguridad, ya que el contenido del portapapeles puede ser confidencial. Compruebe siempre la disponibilidad de la API antes de acceder a sus métodos para evitar errores de referencia nula.

jsdom (utilizado por Jest) no implementa la API del portapapeles. Simúlela en la configuración de las pruebas: Object.assign(navigator, { clipboard: { writeText: jest.fn().mockResolvedValue(undefined) } }). Esto permite comprobar que su componente llama a writeText con el argumento correcto sin necesidad de un entorno de navegador real.

¿Cuándo se puede llamar de forma segura a navigator.clipboard.writeText() en el navegador?

Utilice navigator.clipboard.writeText() dentro de un controlador de clic para copiar texto. Cree un hook useCopyToClipboard que devuelva [copied, copyFn] y restablezca el estado después de un tiempo. Compruebe siempre que la API esté disponible, proporcione una alternativa con execCommand para navegadores antiguos y simule navigator.clipboard en las pruebas de Jest.