HSImage - Hammerspoon 2 API

Bridge type for working with images in JavaScript

HSImage provides a comprehensive API for loading, manipulating, and saving images. It supports various image sources including files, system icons, app bundles, and URLs.

Loading Images

// Load from file
const img = HSImage.fromPath("/path/to/image.png")

// Load system image
const icon = HSImage.fromName("NSComputer")

// Load app icon
const appIcon = HSImage.fromAppBundle("com.apple.Safari")

// Load from URL (asynchronous with Promise)
HSImage.fromURL("https://example.com/image.png")
    .then(image => console.log("Image loaded:", image.size))
    .catch(err => console.error("Failed to load image:", err))

// Or with async/await
const image = await HSImage.fromURL("https://example.com/image.png")

Image Manipulation

const img = HSImage.fromPath("/path/to/image.png")

// Get size
const size = img.size  // Returns HSSize

// Resize image (mutates in place)
img.size = HSSize(100, 100)

// Crop image
const cropped = img.croppedCopy(HSRect(10, 10, 50, 50))

// Save to file
img.saveToFile("/path/to/output.png")

Properties

size

HSSize

The size of the image. Setting this resizes the image in place to the exact dimensions.

Hammerspoon 2/Engine/Types/HSImage.swift:134

name

string

The name of the image, or null if not set.

Hammerspoon 2/Engine/Types/HSImage.swift:143

template

boolean

Whether the image is a template image. Template images are tinted by the system to match the appearance context (e.g. menu bar icons).

Hammerspoon 2/Engine/Types/HSImage.swift:153

Methods

staticHSImage.fromPath(path) -> HSImage

Load an image from a file path

Declaration

HSImage.fromPath(path) -> HSImage

Parameters

Name	Type	Description
path	string	Path to the image file

Returns

HSImage

An HSImage object, or null if the file couldn't be loaded

Example

const img = HSImage.fromPath("/path/to/image.png")

Hammerspoon 2/Engine/Types/HSImage.swift:69

staticHSImage.fromName(name) -> HSImage

Load a system image by name

Declaration

HSImage.fromName(name) -> HSImage

Parameters

Name	Type	Description
name	string	Name of the system image (e.g., "NSComputer", "NSFolder")

Returns

HSImage

An HSImage object, or null if the image couldn't be found

Example

const icon = HSImage.fromName("NSComputer")

Hammerspoon 2/Engine/Types/HSImage.swift:78

staticHSImage.fromSymbol(name) -> HSImage

Load a system symbol by name

Declaration

HSImage.fromSymbol(name) -> HSImage

Parameters

Name	Type	Description
name	string	Name of the symbol (e.g., "hammer", "questionmark.circle")

Returns

HSImage

An HSImage object, or null if the symbol couldn't be found

Example

const sym = HSImage.fromSymbol("star.fill")

Hammerspoon 2/Engine/Types/HSImage.swift:87

staticHSImage.fromAppBundle(bundleID, withFallbackSymbol) -> HSImage

Load an app's icon by bundle identifier

Declaration

HSImage.fromAppBundle(bundleID, withFallbackSymbol) -> HSImage

Parameters

Name	Type	Description
bundleID	string	Bundle identifier of the application
withFallbackSymbol	string	The name of an SF Symbol to use if no bundle image could be loaded. Defaults to questionmark.circle

Returns

HSImage

An HSImage object, or null if the app couldn't be found

Example

const appIcon = HSImage.fromAppBundle("com.apple.Safari")

Hammerspoon 2/Engine/Types/HSImage.swift:98

staticHSImage.iconForFile(path) -> HSImage

Get the icon for a file

Declaration

HSImage.iconForFile(path) -> HSImage

Parameters

Name	Type	Description
path	string	Path to the file

Returns

HSImage

An HSImage object representing the file's icon

Example

const icon = HSImage.iconForFile("/Applications/Safari.app")

Hammerspoon 2/Engine/Types/HSImage.swift:107

staticHSImage.iconForFileType(fileType) -> HSImage

Get the icon for a file type

Declaration

HSImage.iconForFileType(fileType) -> HSImage

Parameters

Name	Type	Description
fileType	string	File extension or UTI (e.g., "png", "public.png")

Returns

HSImage

An HSImage object representing the file type's icon

Example

const icon = HSImage.iconForFileType("pdf")

Hammerspoon 2/Engine/Types/HSImage.swift:116

staticHSImage.fromURL(url) -> Promise<HSImage>

Load an image from a URL (asynchronous)

Declaration

HSImage.fromURL(url) -> Promise<HSImage>

Parameters

Name	Type	Description
url	string	URL string of the image

Returns

Promise<HSImage>

A Promise that resolves to the loaded image, or rejects on error

Example

const img = await HSImage.fromURL("https://example.com/image.png")

Hammerspoon 2/Engine/Types/HSImage.swift:125

copyImage() -> HSImage

Create a copy of the image

Declaration

copyImage() -> HSImage

Returns

HSImage

A new HSImage copy

Example

const copy = img.copyImage()
copy.size = HSSize(64, 64)

Hammerspoon 2/Engine/Types/HSImage.swift:162

croppedCopy(rect) -> HSImage

Create a cropped copy of the image

Declaration

croppedCopy(rect) -> HSImage

Parameters

Name	Type	Description
rect	HSRect	HSRect defining the crop area (x, y, w, h)

Returns

HSImage

A new cropped HSImage, or null if the rect falls outside the image bounds

Example

const cropped = img.croppedCopy(HSRect(10, 10, 80, 60))

Hammerspoon 2/Engine/Types/HSImage.swift:171

saveToFile(path) -> boolean

Save the image to a file

Declaration

saveToFile(path) -> boolean

Parameters

Name	Type	Description
path	string	Destination file path (extension determines format: png, jpg, tiff, bmp, gif)

Returns

boolean

true if saved successfully, false otherwise

Example

img.saveToFile("/tmp/output.png")

Hammerspoon 2/Engine/Types/HSImage.swift:180

set(value) -> None

Replace this image's content. If this image is bound to a UI element, the canvas re-renders automatically.

Declaration

set(value) -> None

Parameters

Name	Type	Description
value	JSValue	A file path string (`~` is expanded) or another HSImage object

Returns

None

Example

const reactive = HSImage.fromName("NSStatusAvailable")
reactive.set("/path/to/image.png")
reactive.set(HSImage.fromName("NSStatusUnavailable"))

Hammerspoon 2/Engine/Types/HSImage.swift:192