hs.sharing
ModuleShare data with other people and apps via macOS sharing services (Mail, Messages, AirDrop, and more).
hs.sharing wraps NSSharingService. Some services from older macOS/Hammerspoon
versions are no longer offered here because Apple removed them from the system:
Aperture (discontinued in 2015) and the built-in Facebook/Twitter/Sina Weibo/Tencent
Weibo/LinkedIn posting and profile-image services (removed in macOS 10.14).
Items to share can be plain strings — treated as a web/mailto URL if they parse as
one, a file path if they start with / or ~ and the file exists, otherwise plain
text — or HSImage objects.
Quick start
hs.sharing.createShare(hs.sharing.builtinServices.mail)
.setCallback((event) => {
if (event === 'didShare') console.log('Sent!')
})
.shareItems(['Check this out', 'https://www.hammerspoon.org'])
Sharing a file via AirDrop
hs.sharing.createShare(hs.sharing.builtinServices.airdrop)
.shareItems(['~/Desktop/photo.jpg'])
Discovering what can handle an item
const services = hs.sharing.servicesFor(['https://www.hammerspoon.org'])
services.forEach(s => console.log(s.title))
Types
This module provides the following types:
Properties
hs.sharing.builtinServices
{[key: string]: string}
A table of shortcut names for the sharing services that are still functional on
modern macOS, mapped to the raw service identifiers `createShare()` expects.
| Key | Service |
|-----|---------|
| `mail` | Compose an email in Mail |
| `message` | Compose a message in Messages |
| `airdrop` | Send via AirDrop |
| `safariReadingList` | Add to Safari's Reading List |
| `photos` | Add to the Photos library |
| `desktopPicture` | Use as the desktop picture |
Methods
hs.sharing.servicesFor(items) -> HSSharingService[]
Finds every sharing service — built-in and third-party (e.g. Notes, Reminders,
installed apps' Share Extensions) — that can handle the given items.
Declaration
hs.sharing.servicesFor(items) -> HSSharingService[]Parameters
| Name | Type | Description |
|---|---|---|
| items | any[] | The items to find services for |
Returns
HSSharingService[]
An array of ready-to-use `HSSharingService` objects
Notes
This uses functionality that was deprecated in macOS 13, it may be removed in a future release
Example
const services = hs.sharing.servicesFor(['hello world'])
services.forEach(s => console.log(s.title))