# simple-mac-clipboard

> simple mac clipboard for node & electron

Latest version **2.2.2** (published 2026-10-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install simple-mac-clipboard
pnpm add simple-mac-clipboard
yarn add simple-mac-clipboard
bun add simple-mac-clipboard
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.2.2 |
| Published | 2026-10-09 |
| First published | 2020-02-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 357.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| GitHub stars | 8 |
| Author | magicdawn |
| Maintainers | magicdawn |
| Keywords | clip, clipboard, mac-clipboard |

## Links

- npm: https://www.npmjs.com/package/simple-mac-clipboard
- Repository: https://github.com/magicdawn/simple-mac-clipboard
- Homepage: https://github.com/magicdawn/simple-mac-clipboard#readme
- Issues: https://github.com/magicdawn/simple-mac-clipboard/issues
- npm.io page: https://npm.io/package/simple-mac-clipboard

## Dependencies (3)

- [bindings](https://npm.io/package/bindings.md) ^1.5.0
- [node-gyp](https://npm.io/package/node-gyp.md) ^13.1.0
- [node-addon-api](https://npm.io/package/node-addon-api.md) ^8.9.2

## Recent versions

- 2.2.2 (latest) — 2026-10-09
- 2.2.1 — 2026-10-03
- 2.2.0 — 2026-06-30
- 2.1.0 — 2026-06-29
- 2.0.0 — 2026-06-29
- 1.3.1 — 2026-06-28
- 1.3.0 — 2026-06-28
- 1.2.4 — 2026-06-16
- 1.2.3 — 2026-06-11
- 1.2.2 — 2026-06-09
- 1.2.1 — 2026-06-09
- 1.2.0 — 2026-06-08
- 1.1.4 — 2025-01-13
- 1.1.3 — 2024-07-07
- 1.1.2 — 2024-07-06
- … 13 more at https://npm.io/package/simple-mac-clipboard/versions

## README

# simple-mac-clipboard

> simple mac clipboard for node & electron

[![npm version](https://img.shields.io/npm/v/simple-mac-clipboard.svg?style=flat-square)](https://www.npmjs.com/package/simple-mac-clipboard)
[![npm downloads](https://img.shields.io/npm/dm/simple-mac-clipboard.svg?style=flat-square)](https://www.npmjs.com/package/simple-mac-clipboard)
[![npm license](https://img.shields.io/npm/l/simple-mac-clipboard.svg?style=flat-square)](http://magicdawn.mit-license.org)

## Install

```sh
$ pnpm add simple-mac-clipboard
```

## Related

https://github.com/electron/electron/issues/9035

## API

> based on https://developer.apple.com/documentation/appkit/nspasteboard

```js
const clip = require('simple-mac-clipboard')
```

### Note

- for read & write, format is required, and format is always the **first** argument
- for write, the boolean return value is for success or not, map from objc `YES` or `NO`

### `clear`

```ts
export function clear(): void
```

clear the clipboard

### `read`

```ts
// single item
export function readBuffer(format: string): Buffer
export function readText(format: string): string

// items
export function readBuffers(format: string): Buffer[]
export function readTexts(format: string): string[]
```

### `write`

#### `writeFormat`

```ts
// typedef
export function writeFormat(format: string, ...datas: Array<Buffer | string | Buffer[] | string[]>): boolean
```

```ts
// example
import clip from 'simple-mac-clipboard'
clip.writeFormat(clip.FORMAT_PLAIN_TEXT, 'text1', Buffer.from('text2'), [Buffer.from('text3'), 'text4'])
```

#### `writePasteboardItems`

```ts
// typedef
export type PasteboardItem = Record<string, Buffer | string>
export function writePasteboardItems(...items: Array<PasteboardItem | PasteboardItem[]>): boolean
```

```ts
// example
import clip from 'simple-mac-clipboard'
clip.writePasteboardItems(
  { 'item1-format1': 'text1' },
  { 'item2-format1': Buffer.from('text2'), 'item2-format2': 'text2', [clip.FORMAT_PLAIN_TEXT]: 'text3' },
)
clip.writePasteboardItems([
  { 'item1-format1': 'text1' },
  { 'item2-format1': Buffer.from('text2'), 'item2-format2': 'text2', [clip.FORMAT_PLAIN_TEXT]: 'text3' },
])
```

#### `declareTypeAndSetData`

> write single item. this method using `NSPasteboard.declareTypes` which supports non-UTI format
> for example `NTPathFinderFilenamesPboardType` equals `dyn.ah62d4rv4gu8y6zcuqf4guvxmr3wgn6wgrf0gn5xbrzw1gydcr7u1e3cytf2gn`
> see https://stackoverflow.com/questions/8003919/are-dynamic-utis-stable & https://alastairs-place.net/blog/2012/06/06/utis-are-better-than-you-think-and-heres-why/

```ts
// typedef
export function declareTypeAndSetData(format: string, data: Buffer | string): boolean
```

```ts
// example
import { declareTypeAndSetData, readText } from 'simple-mac-clipboard'
declareTypeAndSetData('invalid-uti-without-dot', 'invalid-uti-without-dot-content')
expect(readText('invalid-uti-without-dot')).toEqual('invalid-uti-without-dot-content')
```

### predefined `Formats`

`FORMAT_PLAIN_TEXT` / `FORMAT_FILE_URL` / `FORMAT_SOURCE_APP_BUNDLE_ID`

## read/write File Paths

```ts
import { FORMAT_FILE_URL, readTexts, writeFormat } from 'simple-mac-clipboard'
import { fileURLToPath, pathToFileURL } from 'node:url'

const filePaths = ['/tmp/a/b.txt', '/tmp/c']

// write
writeFormat(FORMAT_FILE_URL, ...filePaths.map((p) => pathToFileURL(p).href))

// read
console.log(readTexts(FORMAT_FILE_URL).map((u) => fileURLToPath(u)))
```

## Changelog

[CHANGELOG.md](CHANGELOG.md)

## License

the MIT License http://magicdawn.mit-license.org

---
_Source: https://npm.io/package/simple-mac-clipboard · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._