Electron Documentation1.7.8

Docs / API / nativeImage

nativeImage

Create tray, dock, and application icons using PNG or JPG files.

Process: Main, Renderer

In Electron, for the APIs that take images, you can pass either file paths or NativeImage instances. An empty image will be used when null is passed.

For example, when creating a tray or setting a window’s icon, you can pass an image file path as a String:

const {BrowserWindow, Tray} = require('electron')

const appIcon = new Tray('/Users/somebody/images/icon.png')
let win = new BrowserWindow({icon: '/Users/somebody/images/window.png'})
console.log(appIcon, win)

Or read the image from the clipboard which returns a NativeImage:

const {clipboard, Tray} = require('electron')
const image = clipboard.readImage()
const appIcon = new Tray(image)
console.log(appIcon)

Supported Formats

Currently PNG and JPEG image formats are supported. PNG is recommended because of its support for transparency and lossless compression.

On Windows, you can also load ICO icons from file paths. For best visual quality it is recommended to include at least the following sizes in the:

Check the Size requirements section in this article.

High Resolution Image

On platforms that have high-DPI support such as Apple Retina displays, you can append @2x after image’s base filename to mark it as a high resolution image.

For example if icon.png is a normal image that has standard resolution, then icon@2x.png will be treated as a high resolution image that has double DPI density.

If you want to support displays with different DPI densities at the same time, you can put images with different sizes in the same folder and use the filename without DPI suffixes. For example:

images/
├── icon.png
├── icon@2x.png
└── icon@3x.png
const {Tray} = require('electron')
let appIcon = new Tray('/Users/somebody/images/icon.png')
console.log(appIcon)

Following suffixes for DPI are also supported:

Template Image

Template images consist of black and clear colors (and an alpha channel). Template images are not intended to be used as standalone images and are usually mixed with other content to create the desired final appearance.

The most common case is to use template images for a menu bar icon so it can adapt to both light and dark menu bars.

Note: Template image is only supported on macOS.

To mark an image as a template image, its filename should end with the word Template. For example:

Methods

The nativeImage module has the following methods, all of which return an instance of the NativeImage class:

nativeImage.createEmpty()

Returns NativeImage

Creates an empty NativeImage instance.

nativeImage.createFromPath(path)

Returns NativeImage

Creates a new NativeImage instance from a file located at path. This method returns an empty image if the path does not exist, cannot be read, or is not a valid image.

const nativeImage = require('electron').nativeImage

let image = nativeImage.createFromPath('/Users/somebody/images/icon.png')
console.log(image)

nativeImage.createFromBuffer(buffer[, options])

Returns NativeImage

Creates a new NativeImage instance from buffer.

nativeImage.createFromDataURL(dataURL)

Returns NativeImage

Creates a new NativeImage instance from dataURL.

Class: NativeImage

Natively wrap images such as tray, dock, and application icons.

Process: Main, Renderer

Instance Methods

The following methods are available on instances of the NativeImage class:

image.toPNG([options])

Returns Buffer - A Buffer that contains the image’s PNG encoded data.

image.toJPEG(quality)

Returns Buffer - A Buffer that contains the image’s JPEG encoded data.

image.toBitmap([options])

Returns Buffer - A Buffer that contains a copy of the image’s raw bitmap pixel data.

image.toDataURL([options])

Returns String - The data URL of the image.

image.getBitmap([options])

Returns Buffer - A Buffer that contains the image’s raw bitmap pixel data.

The difference between getBitmap() and toBitmap() is, getBitmap() does not copy the bitmap data, so you have to use the returned Buffer immediately in current event loop tick, otherwise the data might be changed or destroyed.

image.getNativeHandle() macOS

Returns Buffer - A Buffer that stores C pointer to underlying native handle of the image. On macOS, a pointer to NSImage instance would be returned.

Notice that the returned pointer is a weak pointer to the underlying native image instead of a copy, so you must ensure that the associated nativeImage instance is kept around.

image.isEmpty()

Returns Boolean - Whether the image is empty.

image.getSize()

Returns Size

image.setTemplateImage(option)

Marks the image as a template image.

image.isTemplateImage()

Returns Boolean - Whether the image is a template image.

image.crop(rect)

Returns NativeImage - The cropped image.

image.resize(options)

Returns NativeImage - The resized image.

If only the height or the width are specified then the current aspect ratio will be preserved in the resized image.

image.getAspectRatio()

Returns Float - The image’s aspect ratio.

image.addRepresentation(options)

Add an image representation for a specific scale factor. This can be used to explicitly add different scale factor representations to an image. This can be called on empty images.


See something that needs fixing? Propose a change on the source.
Need a different version of the docs? See the available versions or community translations.
Want to search all the documentation at once? See all of the docs on one page.