clipboardy

clipboardy

Access the system clipboard (copy/paste)

Cross-platform. Supports: macOS, Windows, Linux (including Wayland), OpenBSD, FreeBSD, Android with Termux, and modern browsers.

Install

npm install clipboardy

Usage

import clipboard from 'clipboardy';

await clipboard.write('🦄');

await clipboard.read();
//=> '🦄'

// Or use the synchronous API
clipboard.writeSync('🦄');

clipboard.readSync();
//=> '🦄'

API

Browser usage: Requires a secure context (HTTPS). Synchronous methods are not available in browsers.

clipboard

.write(text)

Write (copy) to the clipboard asynchronously.

Returns a Promise<void>.

text

Type: string

The text to write to the clipboard.

await clipboard.write('🦄');

.read()

Read (paste) from the clipboard asynchronously.

Returns a Promise<string>.

const content = await clipboard.read();
//=> '🦄'

.writeSync(text)

Write (copy) to the clipboard synchronously.

Doesn't work in browsers.

text

Type: string

The text to write to the clipboard.

clipboard.writeSync('🦄');

.readSync()

Read (paste) from the clipboard synchronously.

Returns a string.

Doesn't work in browsers.

const content = clipboard.readSync();
//=> '🦄'

.writeImages(filePaths)

Write (copy) images to the clipboard asynchronously.

Returns a Promise<void>.

Only supported on macOS. On other platforms, this is a no-op.

filePaths

Type: string[]

The file paths of the images to write to the clipboard. Supports any image type that macOS supports, including PNG, JPEG, HEIC, WebP, and GIF.

await clipboard.writeImages(['/path/to/image.png']);

.readImages()

Read images from the clipboard asynchronously.

Returns a Promise<string[]> with file paths to temporary PNG files. You are responsible for cleaning up the files.

Only supported on macOS. On other platforms, this returns an empty array.

const filePaths = await clipboard.readImages();

.hasImages()

Check if the clipboard contains images.

Returns a Promise<boolean>.

Only supported on macOS. On other platforms, this returns false.

const hasImages = await clipboard.hasImages();

FAQ

Does this work in headless Linux environments?

No. Clipboard operations on Linux require a display server (X11 or Wayland). Headless environments like CI servers or Raspberry Pi without a desktop environment do not have a system clipboard.

Where can I find the source of the bundled binaries?

The Linux binary is just a bundled version of xsel. The source for the Windows binary can be found here.

On Windows, clipboardy first tries the native PowerShell cmdlets (Set-Clipboard/Get-Clipboard) and falls back to the bundled binary if PowerShell is unavailable or restricted.

Does this work on Wayland?

Yes. On Linux, clipboardy automatically detects Wayland sessions and uses wl-clipboard when available. If not, it gracefully falls back to X11 tools. Also works with WSLg (Windows Subsystem for Linux GUI). Install wl-clipboard using your distribution's package manager.

Related

• clipboard-cli - CLI for this module
• clipboard-image - Get and set images on the clipboard
• copy-text-to-clipboard - Copy text to the clipboard in the browser

Similar packages

Other packages similar to clipboardy

clipboard

The 'clipboard' package is a cross-platform clipboard API for the web. It allows for copying and pasting text within web applications but is not suitable for Node.js server-side applications. It differs from clipboardy in that it is designed for use in the browser rather than in Node.js environments.

copy-paste

The 'copy-paste' package is another Node.js module that provides copy and paste functionality. It is similar to clipboardy but has not been maintained as actively. It may not support as many platforms or have as robust error handling as clipboardy.

clipboard-cli

The 'clipboard-cli' package is a command-line interface for copying and pasting text using the system clipboard. It is built on top of clipboardy and offers a CLI rather than a programmatic API. It is useful for scripting and command-line tasks but not for integrating clipboard functionality into Node.js applications.