> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Extension icons and manifest declarations

> Declare extension icons in manifest fields for branding and action UI. Extension.js validates paths, rewrites references, and emits icon assets.

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`

<img src="https://mintcdn.com/extensionjs/VCnDd7fX2Nza24SE/images/examples/action/screenshot.png?fit=max&auto=format&n=VCnDd7fX2Nza24SE&q=85&s=5e4f6a24e0d133524a58b78e0a1d7585" alt="action template screenshot" width="2400" height="1800" data-path="images/examples/action/screenshot.png" />

An action extension with toolbar icons declared in `manifest.json`.

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest create my-extension --template=action
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest create my-extension --template=action
  ```

  ```bash yarn 2+ theme={null}
  yarn dlx extension@latest create my-extension --template=action
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=action
  ```

  ```bash deno theme={null}
  deno run -A npm:extension@latest create my-extension --template=action
  ```
</CodeGroup>

Repository: [extension-js/examples/action](https://github.com/extension-js/examples/tree/main/examples/action)

## Icon capabilities

| Capability | What it gives you |
| - | - |
| Manifest icon field support | Validate and compile icons for supported extension surfaces |
| Path resolution | Handle relative and public-root icon paths consistently |
| Dev watch updates | Recompile icon changes during local development |
| Browser-safe output | Emit icon assets in extension output with stable references |

## Supported icon fields

| Manifest field | Chromium (Chrome, Edge, Brave, Opera) | Firefox |
| - | - | - |
| `action.default_icon` | .png, .jpg | .png, .jpg, .svg |
| `browser_action.default_icon` | .png, .jpg | .png, .jpg, .svg |
| `icons` | .png, .jpg | .png, .jpg, .svg |
| `page_action.default_icon` | .png, .jpg | .png, .jpg, .svg |
| `sidebar_action.default_icon` | Not supported | .png, .jpg, .svg (\*) |
| `browser_action.theme_icons` | Not supported | .png, .jpg, .svg |

<Note>
  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 (\*).
</Note>

## Sample icon declaration in `manifest.json`

```json theme={null}
{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "icons": {
    "16": "icons/icon-16.png",
    "48": "icons/icon-48.png",
    "128": "icons/icon-128.png"
  },
  "action": {
    "default_icon": "icons/action-icon.png"
  }
}
```

## 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):

```bash theme={null}
for size in 16 32 48 128; do rsvg-convert -w $size -h $size icon.svg -o icons/icon-$size.png; done
```

Then point `icons` and `action.default_icon` at the PNG files, as in the sample above.

## Output path

Typical icon outputs:

```plaintext theme={null}
<path-relative-to-manifest>            # icons keep their source location
browser_action/<theme-icon-filename>   # for theme_icons
```

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.

## Development behavior

* Changing existing icon files triggers recompilation.
* Changing manifest icon entrypoint references can require restarting the dev server.
* 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

* Continue with [web-accessible resources](/docs/implementation-guide/web-accessible-resources).
* Learn more about [Special folders](/docs/features/special-folders).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.