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.

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

Current Tags

5.3.1 ... latest (2 months ago)

clipboardy

Install

Usage

API

clipboard

.write(text)

text

.read()

.writeSync(text)

text

.readSync()

.writeImages(filePaths)

filePaths

.readImages()

.hasImages()

FAQ

Does this work in headless Linux environments?

Where can I find the source of the bundled binaries?

Does this work on Wayland?

Related

Current Tags

29 Versions