Capacitor Clipboard Plugin

Capacitor plugin to read from and write to the system clipboard.

Features

• 📋 Read & Write: Read from and write to the system clipboard.
• 🖼️ Images: Copy and paste real images, not just data URLs as plain text.
• 📝 Rich Text: Write HTML content with a plain-text fallback.
• 🔗 URLs: Copy URLs as native URL clipboard items.
• 🌐 Cross-platform: Works on Android, iOS, and the web.
• 🔒 App Store safe: Uses only official platform APIs.
• 🤝 Compatibility: Works alongside the Share Target and Text Interaction plugins.
• 📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
• 🔁 Up-to-date: Always supports the latest Capacitor version.

Missing a feature? Just open an issue and we'll take a look!

Use Cases

The Clipboard plugin is typically used whenever an app lets users copy or paste content, for example:

• Copy to clipboard buttons: Let users copy coupon codes, invite links, or wallet addresses with one tap.
• Paste support: Read text, URLs, or images from the clipboard into your app, for example into a form or editor.
• Sharing images: Copy a generated image (such as a QR code or chart) so users can paste it into other apps.
• Rich text workflows: Copy formatted HTML content with a plain-text fallback for apps that cannot handle HTML.

Compatibility

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-clipboard` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome/capacitor-clipboard
npx cap sync

Android

No additional configuration is required for this plugin.

iOS

No additional configuration is required for this plugin.

Configuration

No configuration required for this plugin.

Usage

The following examples show how to write text, HTML, images, and URLs to the clipboard, and how to read its current content.

Write text to the clipboard

Copy plain text to the system clipboard:

import { Clipboard } from '@capawesome/capacitor-clipboard';

const writeText = async () => {
  await Clipboard.write({ text: 'Hello World' });
};

Write HTML with a plain-text fallback

Copy HTML content and combine it with text to provide a plain-text fallback for apps that cannot handle HTML content:

import { Clipboard } from '@capawesome/capacitor-clipboard';

const writeHtml = async () => {
  await Clipboard.write({
    html: '<b>Hello World</b>',
    text: 'Hello World',
  });
};

Write an image to the clipboard

Copy a real image (not just a data URL as plain text) by passing a Base64-encoded data URL:

import { Clipboard } from '@capawesome/capacitor-clipboard';

const writeImage = async () => {
  await Clipboard.write({
    image: 'data:image/png;base64,iVBORw0KGgo...',
  });
};

Write a URL to the clipboard

Copy a URL as a native URL clipboard item:

import { Clipboard } from '@capawesome/capacitor-clipboard';

const writeUrl = async () => {
  await Clipboard.write({ url: 'https://capawesome.io' });
};

Read the clipboard content

Read the current content of the system clipboard. The result contains the content type (text, HTML, image, or URL) and the value. Note that on Android, reading the clipboard is only possible while the app is in the foreground, and on iOS, a system paste notification is displayed:

import { Clipboard } from '@capawesome/capacitor-clipboard';

const read = async () => {
  const { type, value } = await Clipboard.read();
  console.log('Type:', type, 'Value:', value);
};

API

• read()
• write(...)
• Interfaces
• Enums

read()

read() => Promise<ReadResult>

Read the current content of the system clipboard.

On Android, reading the clipboard is only possible while the app is in the foreground.

On iOS, reading the clipboard displays a system paste notification. This is expected behavior and cannot be suppressed.

Returns: Promise<ReadResult>

Since: 0.1.0

write(...)

write(options: WriteOptions) => Promise<void>

Write content to the system clipboard.

Exactly one of text, html, image or url must be provided. The html property may additionally be combined with text to provide a plain-text fallback.

Since: 0.1.0

Interfaces

ReadResult

WriteOptions

Enums

ClipboardContentType

Platform Behavior

Android

• On Android 10 (API level 29) and later, apps can only read the clipboard while they are in the foreground and have input focus. The read(...) method rejects otherwise.
• On Android 12 (API level 31) and later, the system shows a toast message when an app reads the clipboard content that was written by another app. This is expected behavior and cannot be suppressed.

iOS

• On iOS 14 and later, the system shows a paste notification banner every time the clipboard is read. This is expected behavior and cannot be suppressed.

Migrating from @capacitor/clipboard

This plugin is a drop-in alternative to the official @capacitor/clipboard plugin with real image support on Android and HTML support on all platforms. The following differences apply:

FAQ

How is this plugin different from other similar plugins?

It supports far more than plain text — copy and paste images, HTML with a plain-text fallback, and native URL items, with reliable real image handling on Android, iOS, and the web. The API is fully typed and actively maintained against the latest OS and framework versions, and it uses only official platform APIs so it stays safe for App Store and Google Play submissions. If you only ever copy plain text, a simpler setup is perfectly fine; if you need rich content and consistent behavior across every platform, this plugin is designed for exactly that.

Why is a notification shown when my app reads the clipboard?

On iOS 14 and later, the system shows a paste notification banner every time the clipboard is read. On Android 12 (API level 31) and later, the system shows a toast message when an app reads clipboard content that was written by another app. Both are expected platform behavior and cannot be suppressed.

Why does reading the clipboard fail on Android?

On Android 10 (API level 29) and later, apps can only read the clipboard while they are in the foreground and have input focus. The read() method rejects otherwise, so make sure to only call it in response to a user interaction while the app is visible.

Can I write multiple content types at once?

No, exactly one of text, html, image or url must be provided when calling write(...). The only exception is that html may additionally be combined with text to provide a plain-text fallback for apps that cannot handle HTML content.

How are images handled by this plugin?

Images are written to the clipboard as real images, not just data URLs as plain text, by passing a Base64-encoded data URL to write(...). When reading, images are also returned as a Base64-encoded data URL. See the usage examples above.

How is this plugin different from the official @capacitor/clipboard plugin?

This plugin is a drop-in alternative to the official @capacitor/clipboard plugin with real image support on Android and HTML support on all platforms. Only a few method options differ, see the migration table above.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

• Share Target: Receive content such as text, links, and files from other apps.
• Text Interaction: Enable and disable text interaction (selection, magnifier, callout menu) in the app's WebView.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.