Nova

Images

Extensions support the use of images for various interface elements (such as the extension’s icon, action buttons, etc.). These images can be included in the extension package, as well as from the set of standard icons provided by the application.

Images are generally specified using an image name, which is a string. This name either references the name of the image within the extension package, or a built-in image name.

Depending on context, there are specific dimensions that are suggested for images:

Context Size (1x) Size (2x)
Main Extension Icon 32x32 64x64
Sidebar Icon (Small) 16x16 32x32
Sidebar Icon (Large) 24x24 48x48
Sidebar List Item 16x16 32x32
Sidebar Header Button 16x16 32x32
Task Template 16x16 32x32
Debug Adapter 16x16 32x32

Specifying images that do not meet these requirements may lead to clipping or improper scaling, especially on retina devices. See below for more information on using Retina assets.

Main Extension Icon

Every extension should have a main icon in the root of its package named extension.png and extension@2x.png (Retina). This icon will be used in the Extension Library both in the application and when published on the web.

This icon should be at least 32x32px (64x64px at 2x). Specifying a larger image will work, but scaling may occur.

Custom Interface Icons

Extensions may include image assets in their package that are available for the user interface.

Currently, custom images can be used in the following contexts:

Image Asset Folders

Each custom image asset should each be placed within an Image Asset Folder folder within the Images/ top-level folder of the extension. This subfolder should use the expected name of the image. To create an image asset named “cloud”, you would create the directory Images/cloud within your extension.

Each image asset folder may also contain a metadata.json file that contains special instructions for handling the asset, such as defining a template image.

Therefore, you might end up with an Images folder that looks like this:

Images/
    cloud/
        metadata.json
        cloud.png
        cloud@2x.png
    arrow/
        metadata.json
        arrow.png
        arrow@2x.png

Supporting Retina Images

Since macOS supports multiple display densities (Retina displays), the extension runtime supports specifying multiple image assets for the appropriate resolution. This is typically done by specifying both 1x and 2x versions of your image assets.

For the main extension icon, you would place extension.png and extension@2x.png images in the root of the extension package.

For custom icons (see below) in the Images/ folder, you would want to specify a cloud subfolder for your icon, and inside would put image assets (preferably PNGs) for the multiple display resolutions, such as cloud.png and cloud@2x.png

Template Images

Image assets also support specifying metadata to determine how they will be handled when rendered. Currently, the only supported metadata is to specify whether the image is a Template. Template images are rendered using standard macOS-style effects and button styles, and automatically handle rendering differently in Light vs. Dark modes. It is generally recommended that any image that uses a singular color be specified as a template image.

To specify a template image, use the template key in the Image Asset Folder metadata file.

{
    "template": true
}

Standard Icons

The extension runtime supports specifying one of several “built-in” standard icons that cover many common use cases, so that assets will match between various extensions.

Standard images can be used in the following contexts:

To use a standard image, specify a string that has the prefix __builtin., followed by the name of the image. For example, to use the standard Add button (a plus icon), you would specify the image name __builtin.add.

The list of available standard images are:

Name Description
action A gear icon suitable for Action buttons
add A plus icon suitable for Add buttons
branch An icon denoting a source control branch
next An arrow icon used for a Next/Forward button
path A stacked layer of lines suitable for denoting a path
previous An arrow icon used for a Previous/Back button
refresh A circular arrow icon suitable for Reload/Refresh buttons
remote A cloud icon denoting a remote server
remove A minus icon suitable for Remove buttons

File Type Icons

The extension runtime also supports requesting the icon for a specific file type. If you would like to display an item with an icon for its type, you can use this functionality to do so.

File type icons can be used in the following contexts:

To request an icon for a specific file type, specify a string that has a prefix __filetype., followed by the file type extension. For a PNG image, you would specify __filetype.png. The application will then attempt to provide the best image for the type, assuming it is one that is supported in either the application or Finder.

Symbol Icons

The extension runtime also supports requesting the icon for a specific symbol type. If you would like to display an item with an icon for a symbol (such as a function, method, or class), you can use this funcitonality to do so.

Symbol icons can be used in the following contexts:

To request an icon for a specific symbol type, specify a string that has a prefix __symbol., followed by the symbol type name.

The set of symbol types are the same as those supported by the Symbol class. The following symbol types are supported:

Types

Callables

Values

Expressions

Stylesets

Tags