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