Skip to main content
Keep extension branding and action UI consistent by declaring icons in manifest fields that Extension.js can validate, rewrite, and emit predictably. Extension.js processes icon paths from manifest.json, resolves public/relative paths, emits icon assets, and watches icon files during development.

Template example

action

action template screenshot An action extension with toolbar icons declared in manifest.json.
Repository: extension-js/templates/action

Icon capabilities

Supported icon fields

Chromium does not accept .svg (or .webp) for icons and action icons. A manifest that points these fields at an SVG loads in Firefox and fails in Chrome, Edge, Brave, and Opera. Ship PNG files for every Chromium target. sidebar_action and browser_action.theme_icons are Firefox fields, and .svg support for sidebar_action.default_icon is partial there (*).

Sample icon declaration in manifest.json

Icon variants

icon_variants declares one icon group per color scheme. Extension.js reads the key at the top level and under action, browser_action, and page_action.
The files under the key ship and are checked like icons:
  • Each variant file is emitted at its source location, and its manifest path follows the same rules as icons.
  • A missing variant file stops the build with the icons error, which names the key: Can't find an icon file listed in icon_variants.
Chromium reads icon_variants only with its ExtensionIconVariants flag on, and Firefox does not read the key yet. For those targets, the build keeps the icons and the action default_icon that your manifest declares. When the manifest has none, the build fills them from the variant group with no color_schemes, then from the light group. Chromium takes PNG sizes only, and Firefox can also take the any SVG. Safari reads icon_variants on its toolbar, from the top level or from action, and prefers it over icons. Measured on Safari 27, it always draws the light group and does not switch to the dark group in dark appearance. Apple’s app converter does not read the key, and it builds the app icon from icons only. So a Safari build gets the same fallback:
  • It keeps icons and the action default_icon when the manifest has them.
  • When the manifest has none, it fills them from the variant group with no color_schemes, then from the light group.
  • It prefers PNG sizes and uses an SVG only when no group has a PNG.
  • icon_variants itself stays in the Safari output, so Apple’s converter still lists the key as unsupported.
The build prints one notice that says which icons the browser shows:
When the build fills icons for you, the notice says so:
On a Safari build, the notice says what the toolbar and the app icon use:
Browser prefixes work on the key. A list under chromium:icon_variants or firefox:icon_variants ships its files in that browser’s build only. See Browser-specific manifest fields.

Generate PNG sizes from an SVG

Keep the SVG as the design source and export the PNG sizes that every browser accepts. This one-liner uses rsvg-convert from librsvg (brew install librsvg on macOS, apt install librsvg2-bin on Debian and Ubuntu):
Then point icons and action.default_icon at the PNG files, as in the sample above.

Output path

Typical icon outputs:
Icons are not moved into an icons/ folder. An icon declared as images/icon.png is emitted at images/icon.png, and the output manifest keeps pointing at that same path.

Path behavior

  • Extension.js resolves relative icon paths from the manifest folder.
  • Leading / and public/... resolve to extension public-root semantics.
  • Extension.js can watch public-folder assets without re-emitting them through the icon feature itself.
  • An icon that a dynamically imported module sets ships beside the worker or page that loads the module. See Runtime-loaded files.

Development behavior

  • Changing existing icon files triggers recompilation.
  • When a manifest edit changes an icon reference, a running extension dev session restarts its compiler by itself.
  • Missing required icon files produce build errors (some optional icon groups can warn instead).

Best practices

  • Declare manifest icon fields explicitly instead of relying on incidental asset imports.
  • Provide multiple icon sizes (16, 32, 48, 128) for sharper UI across browser surfaces.
  • Keep icon filenames stable to reduce manifest churn during development.
  • Use public-root paths intentionally and test resulting manifest output paths.

Next steps