fable-electron-docs-api
nativeImage Type
⚠ Process Availability: Main ✔ | Renderer ✔ | Utility ❌ | Exported ✔
Create tray, dock, and application icons using PNG or JPG files.Process: Main, Renderer> [!IMPORTANT] If you want to call this API from a renderer process with context isolation enabled, place the API call in your preload script and expose it using the contextBridge API.The nativeImage module provides a unified interface for manipulating system images. These can be handy if you want to provide multiple scaled versions of the same icon or take advantage of macOS template images.Electron APIs that take image files accept either file paths or NativeImage instances. An empty and transparent image will be used when null is passed.For example, when creating a Tray or setting a BrowserWindow's icon, you can either pass an image file path as a string:const { BrowserWindow, Tray } = require('electron')const tray = new Tray('/Users/somebody/images/icon.png')const win = new BrowserWindow({ icon: '/Users/somebody/images/window.png' })or generate a NativeImage instance from the same file:### Supported FormatsCurrently, PNG and JPEG image formats are supported across all platforms. 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, we recommend including at least the following sizes:* Small icon * 16x16 (100% DPI scale) * 20x20 (125% DPI scale) * 24x24 (150% DPI scale) * 32x32 (200% DPI scale)* Large icon * 32x32 (100% DPI scale) * 40x40 (125% DPI scale) * 48x48 (150% DPI scale) * 64x64 (200% DPI scale) * 256x256Check the Icon Scaling section in the Windows App Icon Construction reference.:::noteEXIF metadata is currently not supported and will not be taken into account during image encoding and decoding.:::### High Resolution ImageOn platforms that support high pixel density displays (such as Apple Retina), you can append @2x after image's base filename to mark it as a 2x scale 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 Dots per Inch (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 within Electron. For example:images/├── icon.png├── icon@2x.png└── icon@3x.pngconst { Tray } = require('electron')const appTray = new Tray('/Users/somebody/images/icon.png')The following suffixes for DPI are also supported:* @1x* @1.25x* @1.33x* @1.4x* @1.5x* @1.8x* @2x* @2.5x* @3x* @4x* @5x### Template Image _macOS_On macOS, template images consist of black 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 (Tray) icon, so it can adapt to both light and dark menu bars.To mark an image as a template image, its base filename should end with the word Template (e.g. xxxTemplate.png). You can also specify template images at different DPI densities (e.g. xxxTemplate@2x.png).
Static members
| Static member |
Description
|
|
Creates an empty NativeImage instance.
|
Full Usage:
nativeImage.createFromBitmap (buffer, options)
Parameters: Returns: NativeImage
Modifiers: inline |
Creates a new NativeImage instance from buffer that contains the raw bitmap pixel data returned by toBitmap(). The specific format is platform-dependent.
|
Full Usage:
nativeImage.createFromBuffer (buffer, ?width, ?height, ?scaleFactor)
Parameters:
Buffer
?width : int
?height : int
?scaleFactor : float
Returns: NativeImage
Modifiers: inline |
Creates a new NativeImage instance from buffer. Tries to decode as PNG or JPEG first.
|
Full Usage:
nativeImage.createFromDataURL dataURL
Parameters:
string
Returns: NativeImage
Modifiers: inline |
Creates a new NativeImage instance from dataUrl, a base 64 encoded Data URL string.
|
Full Usage:
nativeImage.createFromNamedImage (imageName, ?hslShift)
Parameters:
string
?hslShift : float[]
Returns: NativeImage
Modifiers: inline |
⚠ OS Compatibility: WIN ❌ | MAC ✔ | LIN ❌ | MAS ❌ Creates a new NativeImage instance from the NSImage that maps to the given image name. See Apple's NSImageName documentation for a list of possible values.The hslShift is applied to the image with the following rules:* hsl_shift[0] (hue): The absolute hue value for the image - 0 and 1 map to 0 and 360 on the hue color wheel (red).* hsl_shift[1] (saturation): A saturation shift for the image, with the following key values: 0 = remove all color. 0.5 = leave unchanged. 1 = fully saturate the image.* hsl_shift[2] (lightness): A lightness shift for the image, with the following key values: 0 = remove all lightness (make all pixels black). 0.5 = leave unchanged. 1 = full lightness (make all pixels white).This means that [-1, 0, 1] will make the image completely white and [-1, 1, 0] will make the image completely black.In some cases, the NSImageName doesn't match its string representation; one example of this is NSFolderImageName, whose string representation would actually be NSFolder. Therefore, you'll need to determine the correct string representation for your image before passing it in. This can be done with the following:where SYSTEM_IMAGE_NAME should be replaced with any value from this list.
|
Full Usage:
nativeImage.createFromPath path
Parameters:
string
Returns: NativeImage
Modifiers: inline |
Creates a new NativeImage instance from an image file (e.g., PNG or JPEG) located at path. This method returns an empty image if the path does not exist, cannot be read, or is not a valid image.
|
Full Usage:
nativeImage.createThumbnailFromPath (path, size)
Parameters:
string
size : Size
Returns: Promise<NativeImage>
Modifiers: inline |
⚠ OS Compatibility: WIN ✔ | MAC ✔ | LIN ❌ | MAS ❌ fulfilled with the file's thumbnail preview image, which is a NativeImage.> [!NOTE] Windows implementation will ignore size.height and scale the height according to size.width.
|