@paulmojicatech/native-clipboard

Native context menu with copy, cut, paste, and select all functionality for iOS, Android, and Web.

Features

• 📋 Direct Clipboard Access: Read from and write to the system clipboard
• 🎯 Native Gesture Recognition: Leverages platform-native WebView capabilities
• 🔄 Cross-App Support: Access clipboard content from any app on the device
• 📝 Full Context Menu: Copy, Cut, Paste, and Select All actions
• 🔔 Event Dispatching: Get notified when users perform clipboard actions
• 🌐 Cross-Platform: Works on iOS, Android, and Web
• ⚡ Zero Configuration: Works across the entire app without element targeting
• 🎨 Native UI: Uses platform-native context menus for consistent UX

Install

npm install @paulmojicatech/native-clipboard
npx cap sync

Quick Start

Direct Clipboard Access

import { NativeClipboard } from '@paulmojicatech/native-clipboard';

// Read from clipboard (works with text copied from any app)
const result = await NativeClipboard.read();
console.log('Clipboard:', result.value);

// Write to clipboard
await NativeClipboard.write({ string: 'Hello World!' });

Context Menu

import { NativeClipboard } from '@paulmojicatech/native-clipboard';

// Enable native context menu
await NativeClipboard.enableContextMenu({
  enableCopy: true,
  enablePaste: true,
  enableCut: true,
  enableSelectAll: true
});

// Listen for clipboard actions
NativeClipboard.addListener('clipboardMenuAction', (event) => {
  switch (event.action) {
    case 'copy':
      console.log('User copied:', event.selectedText);
      break;
    case 'paste':
      console.log('User pasted:', event.text);
      // Insert the pasted text into your active element
      break;
    case 'cut':
      console.log('User cut:', event.selectedText);
      // Remove selected text from your UI
      break;
    case 'selectAll':
      console.log('User selected all');
      break;
  }
});

For complete examples with React and Vue, see USAGE_EXAMPLE.md.

API

• echo(...)
• read()
• write(...)
• enableContextMenu(...)
• disableContextMenu()
• addListener('clipboardMenuAction', ...)
• removeAllListeners()
• Interfaces

echo(...)

echo(options: { value: string; }) => Promise<{ value: string; }>

| Param | Type | | ------------- | ------------------------------- | | options | { value: string; } |

Returns: Promise<{ value: string; }>

read()

read() => Promise<{ value: string; }>

Read text from the native clipboard

Returns: Promise<{ value: string; }>

write(...)

write(options: { string: string; }) => Promise<void>

Write text to the native clipboard

| Param | Type | | ------------- | -------------------------------- | | options | { string: string; } |

enableContextMenu(...)

enableContextMenu(options?: { enableCopy?: boolean | undefined; enablePaste?: boolean | undefined; enableCut?: boolean | undefined; enableSelectAll?: boolean | undefined; } | undefined) => Promise<void>

Enable native long press context menu for copy/paste This enables system-level gesture recognition on the WebView

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------------------------- | | options | { enableCopy?: boolean; enablePaste?: boolean; enableCut?: boolean; enableSelectAll?: boolean; } |

disableContextMenu()

disableContextMenu() => Promise<void>

Disable native long press context menu

addListener('clipboardMenuAction', ...)

addListener(eventName: 'clipboardMenuAction', listenerFunc: (event: ClipboardMenuActionEvent) => void) => Promise<PluginListenerHandle>

Add a listener for clipboard context menu events

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------------- | | eventName | 'clipboardMenuAction' | | listenerFunc | (event: ClipboardMenuActionEvent) => void |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin

Interfaces

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

ClipboardMenuActionEvent

| Prop | Type | | ------------------ | ------------------------------------------------------ | | action | 'copy' | 'paste' | 'cut' | 'selectAll' | | text | string | | selectedText | string |

Use Cases

Reading Clipboard from Other Apps

// User copies text in another app (e.g., Notes, Messages, Browser)
// Then opens your app

const clipboardContent = await NativeClipboard.read();
console.log('Got text from other app:', clipboardContent.value);

// Use it in your app
document.getElementById('myInput').value = clipboardContent.value;

Sharing Data Between Apps

// Copy data to clipboard so user can paste in another app
await NativeClipboard.write({
  string: 'https://example.com/share/12345'
});

// Show confirmation
alert('Link copied! You can now paste it anywhere.');

How It Works

iOS

• Uses UIPasteboard.general for direct clipboard access
• Adds a UILongPressGestureRecognizer to the WebView's scroll view
• Shows native iOS context menu using UIMenu (iOS 13+)
• Integrates seamlessly with system clipboard

Android

• Uses ClipboardManager for direct clipboard access
• Overrides WebView's CustomSelectionActionModeCallback
• Uses native Android ActionMode for context menu
• Automatically handles text selection and clipboard operations

Web

• Uses browser's Clipboard API for read/write operations
• Intercepts contextmenu events (right-click)
• Shows custom-styled menu using Clipboard API
• Falls back to browser's default menu if disabled

Permissions

Android

No special permissions required. Clipboard access is automatic.

iOS

No special permissions required. Clipboard access is automatic.

Web

The Clipboard API requires:

• HTTPS (or localhost for development)
• User interaction (satisfied by user-initiated actions)