Docs
Blog
Docs
Blog
🧩

Icons

Icons are used in various parts of the extension interface, including the toolbar, context menus, and the extension settings. Extension.js ensures that all icons defined in the manifest.json file are correctly processed and emitted to the output directory during the build process.

How Does It Work?

Extension.js performs the following tasks for icon resources:

  1. Emit Icon Files: The icon files referenced in the manifest.json are emitted to the output directory of the compilation, ensuring that any updates to the icon files trigger a recompile.
  2. Support for Various Formats: Extension.js supports multiple image formats, including .png, .jpg, and .svg.
  3. Handle Theme Icons: Additional icons, like theme icons, are supported and can be included via the manifest or special folders.

Icon Support

The following manifest fields are used to declare icons:

Manifest Field File Type Expected
action.default_icon .png, .jpg, .svg
browser_action.default_icon .png, .jpg, .svg
icons .png, .jpg, .svg
page_action.default_icon .png, .jpg, .svg
sidebar_action.default_icon .png, .jpg, .svg (*)

Note: Support for .svg is currently partial in some browsers for sidebar_action.default_icon. Review browser compatibility before using SVGs in this context.

Where Icons Appear in Extensions

Icons can appear in different locations across the browser interface, based on where they’re declared in manifest.json:

  • Toolbar Icons: The action.default_icon or browser_action.default_icon fields add an icon in the browser's toolbar, making it visible next to the address bar for user interaction.
  • Context Menus: Declaring icons in page_action.default_icon provides a unique icon specific to certain pages, visible only when defined pages are active.
  • Settings and Extensions Menu: Icons defined under the icons field are used in browser settings or the extension management interface. These icons represent the extension and are usually visible within the browser's extension settings page.
  • Side Panel Icons: The sidebar_action.default_icon icon appears within the side panel of supported browsers, such as Firefox, when the extension opens a custom sidebar interface.

Sample Icon Declaration in manifest.json

Below is a basic example of how to declare icons in your manifest.json:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "icons": {
    "16": "icons/icon-16.png",
    "48": "icons/icon-48.png",
    "128": "icons/icon-128.png"
  },
  "action": {
    "default_icon": "icons/action-icon.png"
  }
}

Using Icons in HTML

When referencing icons in HTML files, icons will be available in the dist folder after building and within a folder based on the feature type. If you want to prevent this behavior, you can use the public folder to store icons and other assets.

Sample HTML File using an icon imported from public folder

Assume the following project structure:

public/
└── icons/
    ├── icon-48.png
    └── icon-128.png

Add the following code to your HTML file to reference the icon:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>My Extension</title>
  </head>
  <body>
    <img src="/icons/icon-48.png" alt="Extension Icon" />
    <script src="scripts/content.js"></script>
  </body>
</html>

Sample HTML File using an icon imported from any other folder

Assume the following project structure:

src/
├── newtab-page.html
└── icons/
    ├── icon-48.png
    └── icon-128.png

Add the following code to your HTML file to reference the icon:

<!-- src/newtab-page.html -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>My Extension</title>
  </head>
  <body>
    <img src="./icons/icon-48.png" alt="Extension Icon" />
    <script src="scripts/content.js"></script>
  </body>
</html>

The output path for icons will be as follows:

dist/
  [browser]
    └── newtab/
        ├── index.html
        └── icon-128.png

Using Icons in JavaScript

You can import icons in JavaScript files using either the import syntax or by referencing the icon path directly via the chrome.runtime.getURL method.

Sample JavaScript File using an icon imported from

Assume the following project structure:

src/
├── scripts/
│   └── content.js
└── icons/
    ├── icon-48.png
    └── icon-128.png

Add the following code to your JavaScript file to reference the icon:

// src/scripts/content.js
import icon48 from "../icons/icon-48.png";

const img = document.createElement("img");
img.src = icon48;
document.body.appendChild(img);

Output Path

The output path for icons follows a structure based on their declared manifest fields. After building, icons are located within the dist/[browser]/ directory, organized as follows:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "icons": {
    "16": "icons/icon-16.png",
    "48": "icons/icon-48.png",
    "128": "icons/icon-128.png"
  },
  "action": {
    "default_icon": "action/icon-16.png"
  }
}
dist/
├── [browser]/
│   ├── action/
│   │   └── icon-16.png
│   ├── icons/
│   │   ├── icon-16.png
│   │   ├── icon-48.png
│   │   ├── icon-128.png
│   │   └── action-icon.png
└── other-extension-files

Best Practices

  • Organize with /public/ Folder: Place additional icons not declared in the manifest within the /public folder to keep project structure clear and ensure they’re accessible if needed.
  • Declare Icons in manifest.json: Always declare icons in the manifest file to ensure they’re correctly bundled in the build process.
  • Provide Multiple Resolutions: Offer icons in multiple resolutions (e.g., 16px, 48px, 128px) to support various device pixel ratios, ensuring icons display clearly on all devices.

Next Steps