Image

The Image class represents an image used for icons and other visual elements across the application. It supports loading images from files, raw pixel buffers, data URLs, and system-named images, as well as transforming them by resizing, cropping, or adding multi-scale representations.

import { Image } from '@mobrowser/api';

Creating images 

There are several ways to create an image in MōBrowser.

From a local file 

The most common way to load an image is from a file on disk using Image.fromLocalImage. Pass the absolute path to a PNG, JPEG, or other image file.

import { app, Image } from '@mobrowser/api';

const image = Image.fromLocalImage(app.getPath('appResources') + '/icon.png')

The method returns an empty image if the file cannot be loaded.

From a data URL 

Use Image.fromDataURL to decode a base64-encoded PNG or JPEG data: URL. Any other data URL type yields an empty image.

import { Image } from '@mobrowser/api';

const image = Image.fromDataURL('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==')

From a buffer 

Use Image.fromBuffer when you have image bytes that may be PNG, JPEG, or raw premultiplied RGBA. The method tries PNG and JPEG decoding first. If both fail, it falls back to reading the buffer as raw RGBA using size and scaleFactor.

import { Image, Size } from '@mobrowser/api';

async function readImageAsUint8Array(url: string) {
  const res = await fetch(url);
  const buffer = await res.arrayBuffer();
  return new Uint8Array(buffer);
}

const imageData = await readImageAsUint8Array('https://example.com/image.png')
const image = Image.fromBuffer(imageData, new Size(16, 16), 1.0)

When you already have a raw pixel buffer of the exact correct length (width × height × 4 bytes), prefer Image.fromBitmap, which takes only raw premultiplied RGBA data and does not attempt PNG or JPEG decoding:

import { Image, Size } from '@mobrowser/api';

// A single transparent pixel.
const image = Image.fromBitmap(new Uint8Array([0x00, 0x00, 0x00, 0x00]), new Size(1, 1), 1.0)

From a named system imagemacOS 

On macOS you can load a named system image or SF Symbol using Image.fromNamedImage. You can optionally pass an HSL shift as a three-element array [hue, saturation, lightness], where each component is in the 0–1 range. Use -1 for hue or 0.5 for saturation/lightness to leave a component unchanged. On other platforms this method returns an empty image.

import { Image } from '@mobrowser/api';

// Load a Bluetooth template icon, keeping its hue and saturation unchanged.
const image = Image.fromNamedImage('NSImageNameBluetoothTemplate', [0.55, 0.5, 0.5])

A full list of Apple’s image name constants is available under NSImage.Name in Apple’s documentation.

File thumbnailmacOSWindows 

Image.thumbnailFromPath asynchronously generates a thumbnail for any file at a given path. The size parameter sets the thumbnail dimensions in pixels.

import { app, Image, Size } from '@mobrowser/api';

const path = app.getPath('appResources') + '/image.png'
const thumbnail = await Image.thumbnailFromPath(path, new Size(100, 100))

Empty image 

Use Image.empty() to create an image with no pixel data. An empty image is useful as an initial value when you intend to build a multi-scale image using addScaleVariant.

import { Image } from '@mobrowser/api';

const image = Image.empty()
console.log(image.isEmpty) // true

Reading image data 

Properties 

The Image class exposes several read-only properties:

Getting the size at a specific scale factor 

Use getSize to obtain the pixel width and height at a given device scale factor:

import { app, Image } from '@mobrowser/api';

const image = Image.fromLocalImage(app.getPath('appResources') + '/icon.png')
const size = image.getSize(2.0)
console.log(size.width, size.height)

Exporting pixel data 

Use asBitmap to get raw premultiplied RGBA pixel data as a Uint8Array (four bytes per pixel) at a given scale factor:

import { app, Image } from '@mobrowser/api';

const image = Image.fromLocalImage(app.getPath('appResources') + '/icon.png')
const bitmap = image.asBitmap(1.0)

Use asDataURL to get a PNG data: URL for the bitmap at a given scale factor:

const dataURL = image.asDataURL(1.0)

Transforming images 

Resizing 

resize returns a new image scaled to the target dimensions. You can specify width, height, or both. If only one dimension is provided, the other is derived from the aspect ratio. The optional scaleFactor adjusts the derived dimension and defaults to 1.0. The quality option controls the resampling filter ('low', 'medium', or 'high').

import { app, Image } from '@mobrowser/api';

const image = Image.fromLocalImage(app.getPath('appResources') + '/icon.png')

// Resize to explicit dimensions.
const resized = image.resize({ width: 64, height: 64 })

// Resize by width only; height is derived from the aspect ratio.
const resizedByWidth = image.resize({ width: 128, quality: 'high' })

Cropping 

crop returns a new image containing the rectangular region defined by a Rect value in pixel coordinates:

import { app, Image } from '@mobrowser/api';

const image = Image.fromLocalImage(app.getPath('appResources') + '/icon.png')
const cropped = image.crop({
  origin: { x: 0, y: 0 },
  size: { width: 100, height: 100 },
})

Multi-scale images 

Use addScaleVariant to attach an additional scale representation to an existing image. This lets you build a single Image that contains both a 1× and a 2× (Retina) variant. Provide either buffer (PNG, JPEG, or raw RGBA bytes) or a dataURL.

import { Image } from '@mobrowser/api';

const image = Image.empty()

image.addScaleVariant({
  scaleFactor: 1.0,
  size: { width: 100, height: 100 },
  dataURL: 'data:image/png;base64,...',
})

image.addScaleVariant({
  scaleFactor: 2.0,
  size: { width: 200, height: 200 },
  dataURL: 'data:image/png;base64,...',
})

console.log(image.scaleFactors) // [1, 2]

Template imagesmacOS 

A template image is rendered as a monochrome shape tinted by the system — useful for toolbar icons and menu bar icons that should adapt to the current appearance (light or dark mode). On other platforms, isTemplateImage is always false and setTemplateImage has no effect.

import { app, Image } from '@mobrowser/api';

const image = Image.fromLocalImage(app.getPath('appResources') + '/icon.png')
image.setTemplateImage(true)
console.log(image.isTemplateImage) // true (macOS), false (Linux, Windows)

See Apple’s documentation for details on how template images are rendered.