hammerspoon2-docs
    Preparing search index...

    Class HSImage

    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.

    // 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")

    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")
    Index

    Constructors

    constructor

    Properties

    name size template

    Methods

    copyImage croppedCopy saveToFile set fromAppBundle fromName fromPath fromSymbol fromURL iconForFile iconForFileType

    Constructors

    Properties

    name: string | null

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

    size: HSSize

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

    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).

    Methods

    • Create a copy of the image

      Returns HSImage | null

      A new HSImage copy

    • Create a cropped copy of the image

      Parameters

      • rect: HSRect

        HSRect defining the crop area (x, y, w, h)

      Returns HSImage | null

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

    • Save the image to a file

      Parameters

      • path: string

        Destination file path (extension determines format: png, jpg, tiff, bmp, gif)

      Returns boolean

      true if saved successfully, false otherwise

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

      Parameters

      • value: string | HSImage

        A file path string (~ is expanded) or another HSImage object

      Returns void

    • Load an app's icon by bundle identifier

      Parameters

      • bundleID: string

        Bundle identifier of the application

      • OptionalwithFallbackSymbol: string

        The name of an SF Symbol to use if no bundle image could be loaded. Defaults to questionmark.circle

      Returns HSImage | null

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

    • Load a system image by name

      Parameters

      • name: string

        Name of the system image (e.g., "NSComputer", "NSFolder")

      Returns HSImage | null

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

    • Load an image from a file path

      Parameters

      • path: string

        Path to the image file

      Returns HSImage | null

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

    • Load a system symbol by name

      Parameters

      • name: string

        Name of the symbol (e.g., "hammer", "questionmark.circle")

      Returns HSImage | null

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

    • Load an image from a URL (asynchronous)

      Parameters

      • url: string

        URL string of the image

      Returns Promise<HSImage>

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

    • Get the icon for a file

      Parameters

      • path: string

        Path to the file

      Returns HSImage | null

      An HSImage object representing the file's icon

    • Get the icon for a file type

      Parameters

      • fileType: string

        File extension or UTI (e.g., "png", "public.png")

      Returns HSImage | null

      An HSImage object representing the file type's icon

    Settings

    Member Visibility

    On This Page

    Loading ImagesImage Manipulation
    Constructors
    Properties
    Methods