theme - Mozilla

theme
=====

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```json
"theme": {
  "images": {
    "theme\_frame": "images/sun.jpg"
  },
  "colors": {
    "frame": "#CF723F",
    "tab\_background\_text": "#000"
  }
}
```
 |

Use the theme key to define a static theme to apply to Firefox.

**Note:** If you want to include a theme with an extension, please see the `theme` API.

**Note:** Since May 2019, themes need to be signed to be installed (Firefox bug 1545109). See Signing and distributing your add-on for more details.

**Note:** A new version of Firefox for Android, based on GeckoView, is under development. A pre-release version is available. The pre-release version does not support themes.

Image formats
-------------

The following image formats are supported in all theme image properties:

* JPEG
* PNG
* APNG
* SVG (animated SVG is supported from Firefox 59)
* GIF (animated GIF isn't supported)
Syntax
------

The theme key is an object that takes the following properties:

| Name | Type | Description |
| --- | --- | --- |
| `images` | `Object` | Optional as of Firefox 60. Mandatory before Firefox 60.

 A JSON object whose properties represent the images to display in
 various parts of the browser. See
 `images` for details on the
 properties that this object can contain.
  |
| `colors` | `Object` | Mandatory.

 A JSON object whose properties represent the colors of various parts
 of the browser. See `colors` for
 details on the properties that this object can contain.
  |
| `properties` | `Object` | Optional

 This object has properties that affect how the
 `"additional_backgrounds"` images are displayed and color schemes are applied. See
 `properties` for details on the properties that this object can contain.
  |

### images

All URLs are relative to the manifest.json file and cannot reference an external URL.

Images should be 200 pixels high to ensure they always fill the header space vertically.

| Name | Type | Description |
| --- | --- | --- |
| `theme_frame` | `String` |
 The URL of a foreground image to be added to the header area and
 anchored to the upper right corner of the header area.

**Note:** Chrome anchors the image to the top left of
 the header and if the image doesn't fill the header area tile the
 image.

Optional in desktop Firefox 60 onwards. Required in Firefox for Android. |
| `additional_backgrounds` | `Array` of `String` |

**Warning:** The
 `additional_backgrounds` property is experimental. It is
 currently accepted in release versions of Firefox, but its behavior
 is subject to change. It is not supported in Firefox for Android.

 An array of URLs for additional background images to be added to the
 header area and displayed behind the
 `"theme_frame":` image. These images layer the first image
 in the array on top, the last image in the array at the bottom.

Optional.

 By default all images are anchored to the upper right corner of the
 header area, but their alignment and repeat behavior can be controlled
 by properties of `"properties":`.
  |

### colors

These properties define the colors used for different parts of the browser. They are all optional. How these properties affect the Firefox UI is shown here:

|  |
| --- |
|
Overview of the color properties and how they apply to Firefox UI components
 |

**Note:** Where a component is affected by multiple color properties, the properties are listed in order of precedence.

All these properties can be specified as either a string containing any valid CSS color string (including hexadecimal), or an RGB array, such as `"tab_background_text": [ 107 , 99 , 23 ]`.

**Note:** In Chrome, colors may only be specified as RGB arrays.

In Firefox for Android colors can be specified using:

* full hexadecimal notation, that is #RRGGBB only. *alpha* and shortened syntax, as in #RGB[A], are not supported.
* Functional notation (RGB arrays) for themes targeting Firefox 68.2 or later.

Colors for Firefox for Android themes cannot be specified using color names.

| Name | Description |
| --- | --- |
| `bookmark_text` |
 The color of text and icons in the bookmark and find bars. Also, if
 `tab_text` isn't defined it sets the color of the active
 tab text and if `icons` isn't defined the color of the
 toolbar icons. Provided as Chrome compatible alias for
 `toolbar_text`.

**Note:** Ensure any color used contrasts well with
 those used in `frame` and `frame_inactive` or
 `toolbar` if you're using that property.

 Where `icons` isn't defined, also ensure good contrast
 with `button_background_active` and
 `button_background_hover`.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "tab\_background\_text": "white",
    "tab\_text": "white",
    "toolbar": "black",
    "bookmark\_text": "red"
  }
}
```

Browser Firefox is black. Browser's tab is black with white text. URL bar and the find in page bar are white with black text but all the browser and the find in page bar icons are red.
 |
| `button_background_active` | The color of the background of the pressed toolbar buttons.

See example

```json
"theme": {
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "button\_background\_active": "red"
  }
}
```

Browser firefox is black. Browser's tabs and URL bar are grey with white text. The customize toolbar icon in the url bar in white with a red background is pressed and a popup is open displaying a short list of thing to add to the toolbar such as the browser's library and the sidebars.
 |
| `button_background_hover` | The color of the background of the toolbar buttons on hover.

See example

```json
"theme": {
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "button\_background\_hover": "red"
  }
}
```

Browser firefox is black. Browser's tabs and URL bar are grey with white text. The go back one page icon is white with a red circle background.
 |
| `icons` | The color of toolbar icons, excluding those in the find toolbar.

**Note:** Ensure the color used contrasts well with
 those used in `frame`, `frame_inactive`,
 `button_background_active`, and
 `button_background_hover`.

See example

```json
"theme": {
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "icons": "red"
  }
}
```

Browser firefox is black. Browser's tabs and URL bar are grey with white text. The URL bar and open a new tab icons are red. The red icons contrast well with the black background color of the header area.
 |
| `icons_attention` |
 The color of toolbar icons in attention state such as the starred
 bookmark icon or finished download icon.

**Note:** Ensure the color used contrasts well with
 those used in `frame`, `frame_inactive`,
 `button_background_active`, and
 `button_background_hover`.

See example

```json
"theme": {
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "icons\_attention": "red"
  }
}
```

Browser firefox is black. Browser's tabs and URL bar are grey with white text. The bookmark this page icon is red and pressed, an open popup name edit this bookmark is displayed. While in attention state, the toolbar icons contrast well with the black background of the header area.
 |
| `frame` |
 The color of the header area background, displayed in the part of the
 header not covered or visible through the images specified in
 `"theme_frame"` and `"additional_backgrounds"`.

See example

```json
"theme": {
  "colors": {
     "frame": "red",
     "tab\_background\_text": "white"
  }
}
```

Browser firefox is red with white text. Browsers tabs are lighter red, also with white text. URL bar is very light red with black text
 |
| `frame_inactive` |
 The color of the header area background when the browser window is
 inactive, displayed in the part of the header not covered or visible
 through the images specified in `"theme_frame"` and
 `"additional_backgrounds"`.

See example

```json
"theme": {
  "colors": {
     "frame": "red",
     "frame\_inactive": "gray",
     "tab\_text": "white"
  }
}
```

Browser firefox is grey. Browser's tabs and URL bar are lighter grey. The tab text is white and the URL bar icon are darker grey.
 |
| `ntp_background` | The new tab page background color.

See example

```json
"theme": {
  "colors": {
     "ntp\_background": "red"
  }
}
```

Firefox showing a new tab page. The background of the page is red.
 |
| `ntp_card_background` | The new tab page card background color.

See example

```json
"theme": {
  "colors": {
     "ntp\_card\_background": "red"
  }
}
```

Firefox showing a new tab page. On the page, the background to the search bar and shortcut buttons is red.
 |
| `ntp_text` | The new tab page text color.

**Note:** Ensure the color used contrasts well with
 that used in `ntp_background` and `ntp_card_background`.

See example

```json
"theme": {
  "colors": {
     "ntp\_text": "red"
  }
}
```

Firefox showing a new tab page. On the page, the text is in red.
 |
| `popup` |
 The background color of popups (such as the URL bar dropdown and the
 arrow panels).

See example

```json
"theme": {
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "popup": "red"
  }
}
```

Browser firefox is black. Browser's tabs and URL bar are lighter grey with icons and text in white. The bookmark this page icon is blue and pressed, an open popup name 'edit this bookmark' is displayed with a red background. The background color of the popup is red.
 |
| `popup_border` | The border color of popups.

See example

```json
"theme": {
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "popup": "black",
     "popup\_text": "white",
     "popup\_border": "red"
  }
}
```

Browser firefox is black. Browser's tabs and URL bar are lighter grey with icons and text in white. The bookmark this page icon is blue and pressed, an open popup name 'edit this bookmark' is displayed with a red outline and black background. The popup's border is red.
 |
| `popup_highlight` |
 The background color of items highlighted using the keyboard inside
 popups (such as the selected URL bar dropdown item).

**Note:** It's recommended to define
 `popup_highlight_text` to override the browser default
 text color on various platforms.

See example

```json
"theme": {
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "popup\_highlight": "red",
     "popup\_highlight\_text": "white"
  }
}
```

screenshot of firefox is black. Browser's tabs and URL bar are lighter grey with icons and text in white. A search results popup is displayed with a highlighted item's background in red. The background color of the highlighted item inside the popup is red.
 |
| `popup_highlight_text` | The text color of items highlighted inside popups.

**Note:** Ensure the color used contrasts well with
 that used in `popup_highlight`.

See example

```json
"theme": {
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "popup\_highlight": "black",
     "popup\_highlight\_text": "red"
  }
}
```

Browser firefox is black. Browser's tabs and URL bar are lighter grey with icons and text in white. A search results popup is displayed with a highlighted item's text in red with a black background. The text color of the highlighted item contrasts well with the black background color of this item.
 |
| `popup_text` | The text color of popups.

**Note:** Ensure the color used contrasts well with
 that used in `popup`.

See example

```json
"theme": {
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "popup": "black",
     "popup\_text": "red"
  }
}
```

Browser firefox is black. Browser's tabs and URL bar are lighter grey with icons and text in white. A search results popup is displayed with items texts in red. The text color contrasts well with the black background color of the popup.
 |
| `sidebar` | The background color of the sidebar.

See example

```json
"theme": {
  "colors": {
     "sidebar": "red",
     "sidebar\_highlight": "white",
     "sidebar\_highlight\_text": "green",
     "sidebar\_text": "white"
  }
}
```

A close-up screenshot of a browser windows's open sidebar. The background color of the sidebar is red.
 |
| `sidebar_border` | The border and splitter color of the browser sidebar

See example

```json
"theme": {
  "colors": {
     "sidebar\_border": "red"
  }
}
```

A closeup of the firefox browser bookmarks sidebar with a red horizontal separator between the sidebar title and the sidebar menu. The border and splitter color of the sidebar is red.
 |
| `sidebar_highlight` | The background color of highlighted rows in built-in sidebars

See example

```json
"theme": {
  "colors": {
     "sidebar\_highlight": "red",
     "sidebar\_highlight\_text": "white"
  }
}
```

A closeup of the firefox browser bookmarks sidebar with a highlighted item. The background color of a highlighted row in the sidebar is red with white text.
 |
| `sidebar_highlight_text` | The text color of highlighted rows in sidebars.

**Note:** Ensure the color used contrasts well with
 that used in `sidebar_highlight`.

See example

```json
"theme": {
  "colors": {
    "sidebar\_highlight": "pink",
    "sidebar\_highlight\_text": "red",
  }
}
```

A closeup of the firefox browser bookmarks sidebar with a highlighted item. The color of the text of a highlighted row in the sidebar is red. The text color contrasts well with the pink background color of the highlighted row.
 |
| `sidebar_text` | The text color of sidebars.

**Note:** Ensure the color used contrasts well with
 that used in `sidebar`.

See example

```json
"theme": {
  "colors": {
     "sidebar": "red",
     "sidebar\_highlight": "white",
     "sidebar\_highlight\_text": "green",
     "sidebar\_text": "white"
  }
}
```

A close-up screenshot of a browser windows's open sidebar. The color of the text inside the sidebar is white. The text color contrasts well with the red background of the sidebar.
 |
| `tab_background_separator`
Deprecated
 |

**Warning:** `tab_background_separator` is
 not supported starting with Firefox 89.

The color of the vertical separator of the background tabs.

See example

```json
"theme": {
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "tab\_background\_separator": "red"
  }
}
```

A closeup of browser tabs to highlight the separator.
 |
| `tab_background_text` |
 The color of the text displayed in the inactive page tabs. If
 `tab_text` or `bookmark_text` isn't specified,
 applies to the active tab text.

**Note:** Ensure the color used contrasts well with
 those used in `tab_selected` or `frame` and
 `frame_inactive`.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "white",
    "tab\_background\_text": "red"
  }
}
```

A screenshot of a browser window with one open tab. Browser is black. Browser's tabs and URL bar are white with red icons and red text. The color of the text in the open tab is red. The text color contrasts well with the black background color of the tab.
 |
| `tab_line` | The color of the selected tab line.

See example

```json
"theme": {
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "tab\_line": "red"
  }
}
```

Browser firefox is black. Browser's tabs and URL bar are darker grey with lighter grey icons and white text. The selected tab has a red outline.
 |
| `tab_loading` | The color of the tab loading indicator and the tab loading burst.

See example

```json
"theme": {
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "tab\_loading": "red"
  }
}
```

A screenshot of a browser window with one open tab. Browser is black. Browser's tabs and URL bar are darker grey with icons and text in white. Inside the selected tab an animated loading indicator is red.
 |
| `tab_selected` |
 The background color of the selected tab. When not in use selected tab
 color is set by `frame` and the
 `frame_inactive`.

See example

```json
"theme": {
  "images": {
  "theme\_frame": "weta.png"
},
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "tab\_selected": "red"
  }
}
```

A screenshot of a browser window with one open tab. Browser is black. Browser's tabs and URL bar are darker grey with icons and text in white. The selected tab has red background and white text.
 |
| `tab_text` |
 From Firefox 59, it represents the text color for the selected tab. If
 `tab_line` isn't specified, it also defines the color of
 the selected tab line.

**Note:** Ensure the color used contrasts well with
 those used in `tab_selected` or `frame` and
 `frame_inactive`.

See example

```json
"theme": {
  "images": {
  "theme\_frame": "weta.png"
},
  "colors": {
     "frame": "black",
     "tab\_background\_text": "white",
     "tab\_selected": "white",
     "tab\_text": "red"
  }
}
```

Browser firefox has a picture of an insect theme. URL bar is lighter grey with white icons. The selected tab text is red with white background.
 |
| `toolbar` |
 The background color for the navigation bar, the bookmarks bar, and
 the selected tab.

This also sets the background color of the "Find" bar.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "red",
    "tab\_background\_text": "white"
  }
}
```

Browser firefox is black. Browser's tab, find in page bar and URL bar are red with white text and icons, except for the find in page bar where the text and icon are black.
 |
| `toolbar_bottom_separator` |
 The color of the line separating the bottom of the toolbar from the
 region below.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "tab\_background\_text": "white",
    "toolbar\_bottom\_separator": "red"
  }
}
```

Browser firefox is black. Browser's tab and URL bar are lighter grey with white text and icons. A horizontal red line separates the bottom of the toolbar and the beginning of the display of the web page.
 |
| `toolbar_field` | The background color for fields in the toolbar, such as the URL bar.

 This also sets the background color of the
 **Find in page** field.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "tab\_background\_text": "white",
    "toolbar\_field": "red"
  }
}
```

Browser firefox is black. Browser's tab, find in page bar and URL bar are lighter grey with white text and icons. The background color of the URL bar is red. The find in page bar is white with black text. The find in page field is red with black text.
 |
| `toolbar_field_border` | The border color for fields in the toolbar.

 This also sets the border color of the
 **Find in page** field.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "black",
    "tab\_background\_text": "white",
    "toolbar\_field": "black",
    "toolbar\_field\_text": "white",
    "toolbar\_field\_border": "red"
  }
}
```

Browser firefox is black. Browser's tab, find in page and URL bar are black with white text and icons. The URL bar and find in page fields are outlined in red.
 |
| `toolbar_field_border_focus` | The focused border color for fields in the toolbar.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "black",
    "tab\_background\_text": "white",
    "toolbar\_field": "black",
    "toolbar\_field\_text": "white",
    "toolbar\_field\_border\_focus": "red"
  }
}
```

Browser firefox is black. Browser's tab and URL bar are black with white text and icons. The url bar field is focused and outlined in red.
 |
| `toolbar_field_focus` |
 The focused background color for fields in the toolbar, such as the
 URL bar.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "black",
    "tab\_background\_text": "white",
    "toolbar\_field": "black",
    "toolbar\_field\_text": "white",
    "toolbar\_field\_focus": "red"
  }
}
```

Browser firefox is black. Browser's tab, find in page and URL bar are black with white text and icons. The background color of the focused URL bar is red and the text is white.
 |
| `toolbar_field_highlight` |
 The background color used to indicate the current selection of text in
 the URL bar (and the search bar, if it's configured to be separate).

See example

```json
"theme": {
  "colors": {
    "toolbar\_field": "rgb(255 255 255 / 91%)",
    "toolbar\_field\_text": "rgb(0 100 0)",
    "toolbar\_field\_highlight": "rgb(180 240 180 / 90%)",
    "toolbar\_field\_highlight\_text": "rgb(0 80 0)"
  }
}
```

Browser firefox is white. Browser's tab and URL bar are white with text and icons in black. The URL bar field is focused and outlined in blue and URL bar text is selected.

 Here, the `toolbar_field_highlight` field specifies that
 the highlight color is a light green, while the text is set to a
 dark-to-medium green using `toolbar_field_highlight_text`.
  |
| `toolbar_field_highlight_text` |
 The color used to draw text that's currently selected in the URL bar
 (and the search bar, if it's configured to be separate box).

**Note:** Ensure the color used contrasts well with
 those used in `toolbar_field_highlight`.

See example

```json
"theme": {
  "colors": {
    "toolbar\_field": "rgb(255 255 255 / 91%)",
    "toolbar\_field\_text": "rgb(0 100 0)",
    "toolbar\_field\_highlight": "rgb(180 240 180 / 90%)",
    "toolbar\_field\_highlight\_text": "rgb(0 80 0)"
  }
}
```

Browser firefox is white. Browser's tab and URL bar are white with text and icons in black. The URL bar field is focused and outlined in blue and URL bar text is selected.

 Here, the `toolbar_field_highlight_text` field is used to
 set the text color to a dark medium-dark green, while the highlight
 color is a light green.
  |
| `toolbar_field_separator`
Deprecated
 |

**Warning:** `toolbar_field_separator` is
 not supported starting with Firefox 89.

 The color of separators inside the URL bar. In Firefox 58 this was
 implemented as `toolbar_vertical_separator`.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "black",
    "tab\_background\_text": "white",
    "toolbar\_field\_separator": "red"
  }
}
```

A screenshot of a browser window with one open tab. Browser firefox is black. Browser's tab and URL bar are black with text and icons in white. Inside the white URL bar field, after the reader mode icon a red vertical line separating the rest of URL bar icons. The color of the vertical separator line inside the URL bar is red.

 In this screenshot, `"toolbar_vertical_separator"` is the
 red vertical line in the URL bar dividing the Reader Mode icon from
 the other icons.
  |
| `toolbar_field_text` |
 The color of text in fields in the toolbar, such as the URL bar. This
 also sets the color of text in the
 **Find in page** field.

**Note:** Ensure the color used contrasts well with
 those used in `toolbar_field`.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "black",
    "tab\_background\_text": "white",
    "toolbar\_field": "black",
    "toolbar\_field\_text": "red"
  }
}
```

A screenshot of a browser window with one open tab. Browser is black. Browser's tab and URL bar are black with white text and icons. The text inside the URL bar is red. The icons and find in page field have red text with black background.
 |
| `toolbar_field_text_focus` |
 The color of text in focused fields in the toolbar, such as the URL
 bar.

**Note:** Ensure the color used contrasts well with
 those used in `toolbar_field_focus`.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "toolbar": "black",
    "tab\_background\_text": "white",
    "toolbar\_field": "black",
    "toolbar\_field\_text": "white",
    "toolbar\_field\_text\_focus": "red"
  }
}
```

A screenshot of a browser window with two open tabs. Browser is black. Browser's tab and URL bar are black with text and icons in white. The URL bar has focus; the bar's text and icons are red with black background.
 |
| `toolbar_text` |
 The color of toolbar text. This also sets the color of text in the
 "Find" bar.

**Note:** For compatibility with Chrome, use the alias
 `bookmark_text`.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "tab\_background\_text": "white",
    "toolbar": "black",
    "toolbar\_text": "red"
  }
}
```

A screenshot of a browser window with one open tab. Browser is black. Browser's tab, find in page bar, and URL bar are black with red text and icons. The text inside the active tab, the navigator bar and the find bar is red.
 |
| `toolbar_top_separator` |
 The color of the line separating the top of the toolbar from the
 region above.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "tab\_background\_text": "white",
    "toolbar": "black",
    "toolbar\_top\_separator": "red"
  }
}
```

A screenshot of a browser window with one open tab. Browser is black. Browser's tab and URL bar are black with white text and icons. A red line separates the top of the URL bar from the browser.
 |
| `toolbar_vertical_separator` |
 The color of the separator in the bookmarks toolbar. In Firefox 58, it
 corresponds to the color of separators inside the URL bar.

See example

```json
"theme": {
  "colors": {
    "frame": "black",
    "tab\_background\_text": "white",
    "toolbar": "black",
    "toolbar\_vertical\_separator": "red"
  }
}
```

A screenshot of a browser window with one open tab. Browser is black. Browser's tab and URL bar are black with text and icons in white. The color of the vertical line separating the bookmarks toolbar from the content to the right is red.
 |

#### Aliases

Additionally, this key accepts various properties that are aliases for one of the properties above. These are provided for compatibility with Chrome. If an alias is given, and the non-alias version is also given, then the value will be taken from the non-alias version.

| Name | Alias for |
| --- | --- |
| `bookmark_text` | `toolbar_text` |

### properties

| Name | Type | Description |
| --- | --- | --- |
| `additional_backgrounds_alignment` | `Array` of `String` | Optional

 An array of enumeration values defining the alignment of the
 corresponding `"additional_backgrounds":` array item.The
 alignment options include:
 * `"bottom"`
* `"center"`
* `"left"`
* `"right"`
* `"top"`
* `"center bottom"`
* `"center center"`
* `"center top"`
* `"left bottom"`
* `"left center"`
* `"left top"`
* `"right bottom"`
* `"right center"`
* `"right top"`.

If not specified, defaults to `"right top"`. |
| `additional_backgrounds_tiling` | `Array` of `String` | Optional

 An array of enumeration values defining how the corresponding
 `"additional_backgrounds":` array item repeats. Options
 include:
 * `"no-repeat"`
* `"repeat"`
* `"repeat-x"`
* `"repeat-y"`

If not specified, defaults to `"no-repeat"`. |
| `color_scheme` | `String` | Optional

 Determines which color scheme is applied to the chrome (for example, context menus)
 and content (for example, built-in pages and the preferred color scheme for web pages).
 Options include:
 * `"auto"` – a light or dark scheme based automatically on the theme.
* `"light"` – a light scheme.
* `"dark"` – a dark scheme.
* `"system"` – uses the system scheme.

If not specified, defaults to `"auto"`. |
| `content_color_scheme` | `String` | Optional

 Determines which color scheme is applied to the content (for example, built-in pages and
 preferred color scheme for web pages). Overrides `color_scheme`. Options
 include:
 * `"auto"` – a light or dark scheme based automatically on the theme.
* `"light"` – a light scheme.
* `"dark"` – a dark scheme.
* `"system"` – the system scheme.

If not specified, defaults to `"auto"`. |

Examples
--------

A basic theme must define an image to add to the header, the accent color to use in the header, and the color of text used in the header:

```json
 "theme": {
   "images": {
     "theme\_frame": "images/sun.jpg"
   },
   "colors": {
     "frame": "#CF723F",
     "tab\_background\_text": "#000"
   }
 }
```

Multiple images can be used to fill the header. Before Firefox version 60, use a blank or transparent header image to gain control over the placement of each additional image:

```json
 "theme": {
   "images": {
     "additional\_backgrounds": [ "images/left.png", "images/middle.png", "images/right.png"]
   },
   "properties": {
     "additional\_backgrounds\_alignment": [ "left top", "top", "right top"]
   },
   "colors": {
     "frame": "blue",
     "tab\_background\_text": "#ffffff"
   }
 }
```

You can also fill the header with a repeated image, or images, in this case a single image anchored in the middle top of the header and repeated across the rest of the header:

```json
 "theme": {
   "images": {
     "additional\_backgrounds": [ "images/logo.png"]
   },
   "properties": {
     "additional\_backgrounds\_alignment": [ "top" ],
     "additional\_backgrounds\_tiling": [ "repeat"  ]
   },
   "colors": {
     "frame": "green",
     "tab\_background\_text": "#000"
   }
 }
```

The following example uses most of the different values for `theme.colors`:

```json
  "theme": {
    "images": {
      "theme\_frame": "weta.png"
    },

    "colors": {
       "frame": "darkgreen",
       "tab\_background\_text": "white",
       "toolbar": "blue",
       "bookmark\_text": "cyan",
       "toolbar\_field": "orange",
       "toolbar\_field\_border": "white",
       "toolbar\_field\_text": "green",
       "toolbar\_top\_separator": "red",
       "toolbar\_bottom\_separator": "white",
       "toolbar\_vertical\_separator": "white"
    }
  }
```

It will give you a browser that looks like this:

![A browser window with two open tabs and dark green background color in the header area. The inactive tab has a white text color. The active tab and the toolbar have a blue background color with cyan-colored text. The URL bar has an orange background with white borders, a green text color and a white-colored vertical line separator. A red-colored line is used to separate the tabs on the top and a white line to separate the tabs from the content bellow them.](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/theme/theme.png)

In this screenshot, `"toolbar_vertical_separator"` is the white vertical line in the URL bar dividing the Reader Mode icon from the other icons.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### Chrome compatibility

In Chrome:

* `colors/toolbar_text` is not used, use `colors/bookmark_text` instead.
* `images/theme_frame` anchors the image to the top left of the header and if the image doesn't fill the header area tile the image.
* all colors must be specified as an array of RGB values, like this:

```json
"theme": {
  "colors": {
     "frame": [255, 0, 0],
     "tab\_background\_text": [0, 255, 0],
     "bookmark\_text": [0, 0, 255]
  }
}
```

From Firefox 59 onward, both the array form and the CSS color form are accepted for all properties. Before that, `colors/frame` and `colors/tab_background_text` required the array form, while other properties required the CSS color form.


icons - Mozilla

icons
=====

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory | No |
| Manifest version | 2 or higher |

The `icons` key specifies icons for your extension. Those icons will be used to represent the extension in components such as the Add-ons Manager.

It consists of key-value pairs of image size in px and image path relative to the root directory of the extension.

If `icons` is not supplied, a standard extension icon will be used by default.

You should supply at least a main extension icon, ideally 48x48 px in size. This is the default icon that will be used in the Add-ons Manager. You may, however, supply icons of any size and Firefox will attempt to find the best icon to display in different components.

Firefox will consider the screen resolution when choosing an icon. To deliver the best visual experience to users with high-resolution displays, such as Retina displays, provide double-sized versions of all your icons.

Example
-------

The keys in the `icons` object specify the icon size in px, values specify the relative icon path. This example contains a 48px extension icon and a larger version for high-resolution displays.

```json
"icons": {
  "48": "icon.png",
  "96": "icon@2x.png"
}
```

SVG
---

You can use SVG and the browser will scale your icon appropriately. There are currently two caveats though:

1. You need to specify a viewBox in the image. E.g.:

```html
<svg
 xmlns="http://www.w3.org/2000/svg"
 viewBox="0 0 48 48"
 width="48"
 height="48">
  <!-- your svg content -->
</svg>
```

2. Even though you can use one file, you still need to specify various size of the icon in your manifest. E.g.:

```json
"icons": {
  "48": "icon.svg",
  "96": "icon.svg"
}
```

**Note:** Only Firefox is known to support SVG icons. Chromium has a bug about unsupported SVG icons.

**Note:** Remember to include the `xmlns` attribute when creating the SVG. Otherwise, Firefox won't be able to display the icon.

**Note:** If you are using a program like Inkscape for creating SVG, you might want to save it as a "plain SVG". Firefox might be confused by various special namespaces and not display your icon.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


browser_action - Mozilla

browser\_action
===============

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory | No |
| Manifest version | 2 |
| Example |
```json
"browser\_action": {
  "default\_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default\_title": "Whereami?",
  "default\_popup": "popup/geo.html",
  "theme\_icons": [{
    "light": "icons/geo-16-light.png",
    "dark": "icons/geo-16.png",
    "size": 16
  }, {
    "light": "icons/geo-32-light.png",
    "dark": "icons/geo-32.png",
    "size": 32
  }]
}
```
 |

A browser action is a button that your extension adds to the browser's toolbar. The button has an icon, and may optionally have a popup whose content is specified using HTML, CSS, and JavaScript.

This key is replaced by `action` in Manifest V3 extensions.

If you supply a popup, then the popup is opened when the user clicks the button, and your JavaScript running in the popup can handle the user's interaction with it. If you don't supply a popup, then a click event is dispatched to your extension's background scripts when the user clicks the button.

You can also create and manipulate browser actions programmatically using the browserAction API.

Syntax
------

The `browser_action` key is an object that may have any of the following properties, all optional:

| Name | Type | Description |
| --- | --- | --- |
| `browser\_style`Optional | `Boolean` | Optional, defaulting to `false`.

Do not set `browser_style` to true: it isn't supported in Manifest V3, starting with Firefox 118. See Manifest V3 migration for `browser_style`.

 In Firefox, the stylesheet can be seen at
 chrome://browser/content/extension.css or
 chrome://browser/content/extension-mac.css on macOS. When setting
 dimensions, be aware that this stylesheet sets
 `box-sizing: border-box` (see
 box-sizing).

Browser styles describes the classes you can apply to elements in the popup
 to get particular styles.

 The
 latest-download
 example extension uses `browser_style` in its popup.

**Note:** Setting `browser_style` to
 `true` prevents users from selecting text in an
 extension's popup or sidebar content. This is normal behavior. You
 can't select parts of the UI in the browser. However, you can work
 around this limitation to allow your users to select text in two
 ways:

1. Set `browser_style` to `false`.
2. Use CSS styling on the body of your sidebar or popup's HTML to
 allow text selection by adding the rule
 `-moz-user-select` with a value of `all` or
 `text`.

 |
| `default_area`Optional | `String` |
 Defines the part of the browser in which the button is initially
 placed. This is a string that may take one of four values:
 * "navbar": the button is placed in the main browser toolbar,
 alongside the URL bar.
* "menupanel": the button is placed in a popup panel.
* "tabstrip": the button is placed in the toolbar that contains
 browser tabs.
* "personaltoolbar": the button is placed in the bookmarks toolbar.

This property is only supported in Firefox.
This property is optional, and defaults to "menupanel".

 Firefox remembers the `default_area` setting for an
 extension, even if that extension is uninstalled and subsequently
 reinstalled. To force the browser to acknowledge a new value for
 `default_area`, the id of the extension must be changed.

 An extension can't change the location of the button after it has been
 installed, but the user may be able to move the button using the
 browser's built-in UI customization mechanism.
  |
| `default_icon`Optional | `Object` or `String` |
 Use this to specify one or more icons for the browser action. The icon
 is shown in the browser toolbar by default.

Icons are specified as URLs relative to the manifest.json file itself.
You can specify a single icon file by supplying a string here:

```json
"default\_icon": "path/to/geo.svg"
```

 To specify multiple icons in different sizes, specify an object here.
 The name of each property is the icon's height in pixels, and must be
 convertible to an integer. The value is the URL. For example:

```json
    "default\_icon": {
      "16": "path/to/geo-16.png",
      "32": "path/to/geo-32.png"
    }
```

 You cannot specify multiple icons of the same sizes.See
 Choosing icon sizes
 for more guidance on this.
  |
| `default_popup`Optional | `String` | The path to an HTML file containing the specification of the popup.

 The HTML file may include CSS and JavaScript files using
 `<link>`
 and
 `<script>`
 elements, just like a normal web page. However,
 `<script>`must have
 `src`
 attribute to load a file. Don't use
 `<script>`
 with embedded code, because you'll get a confusing Content Violation
 Policy error.

 Unlike a normal web page, JavaScript running in the popup can access
 all the
 WebExtension APIs
 (subject, of course, to the extension having the appropriate
 permissions).

 This is a
 localizable property.
  |
| `default_title`Optional | `String` |
 Tooltip for the button, displayed when the user moves their mouse over
 it. If the button is added to the browser's menu panel, this is also
 shown under the app icon.

 This is a
 localizable property.
  |
| `theme_icons`Optional | `Array` |
 This property enables you to specify different icons for themes
 depending on whether Firefox detects that the theme uses dark or light
 text.

 If this property is present, it's an array containing at least one
 `ThemeIcons` object. A `ThemeIcons` object
 contains three mandatory properties:

`"dark"`

 A URL pointing to an icon. This icon displays when a theme using
 dark text is active (such as the Firefox Light theme, and the
 Default theme if no default\_icon is specified).

`"light"`

 A URL pointing to an icon. This icon displays when a theme using
 light text is active (such as the Firefox Dark theme).

`"size"`
The size of the two icons in pixels.

Icons are specified as URLs relative to the manifest.json file.

 You should supply 16x16 and 32x32 (for retina display)
 `ThemeIcons`.
  |

Choosing icon sizes
-------------------

The browser action's icon may need to be displayed in different sizes in different contexts:

* The icon is displayed in the browser toolbar. Older versions of Firefox supported the option of placing the icon in the browser's menu panel (the panel that opens when the user clicks the "hamburger" icon). In those versions of Firefox the icon in the menu panel was larger than the icon in the toolbar.
* On a high-density display like a Retina screen, icons needs to be twice as big.

If the browser can't find an icon of the right size in a given situation, it will pick the best match and scale it. Scaling may make the icon appear blurry, so it's important to choose icon sizes carefully.

There are two main approaches to this. You can supply a single icon as an SVG file, and it will be scaled correctly:

```json
"default\_icon": "path/to/geo.svg"
```

Alternatively, you can supply several icons in different sizes, and the browser will pick the best match.

In Firefox:

* The default height and width for icons in the toolbar is 16 \* `window.devicePixelRatio`.
* The default height and width for icons in the menu panel is 32 \* `window.devicePixelRatio`.

So you can specify icons that match exactly, on both normal and Retina displays, by supplying three icon files, and specifying them like this:

```json
"default\_icon": {
  "16": "path/to/geo-16.png",
  "32": "path/to/geo-32.png",
  "64": "path/to/geo-64.png"
}
```

If Firefox can't find an exact match for the size it wants, then it will pick the smallest icon specified that's bigger than the ideal size. If all icons are smaller than the ideal size, it will pick the biggest icon specified.

Example
-------

```json
"browser\_action": {
  "default\_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  }
}
```

A browser action with just an icon, specified in 2 different sizes. The extension's background scripts can receive click events when the user clicks the icon using code like this:

```js
browser.browserAction.onClicked.addListener(handleClick);
```

```json
"browser\_action": {
  "default\_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default\_title": "Whereami?",
  "default\_popup": "popup/geo.html"
}
```

A browser action with an icon, a title, and a popup. The popup will be shown when the user clicks the button.

For a simple, but complete, extension that uses a browser action, see the walkthrough tutorial.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `page_action`
* `sidebar_action`
* Browser styles


dictionaries - Mozilla

dictionaries
============

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```json
"dictionaries": {
  "en-US": "dictionaries/en-US.dic"
}
```
 |

The `dictionaries` key specifies the `locale_code` for which your extension supplies a dictionary. Although the dictionary consists of two files, one with a `.dic` and one with an `.aff` file extension, only the one with the `.dic` extension is referenced in the manifest.json.

If you use the `dictionaries` key, you must also set an ID for your extension using the `browser_specific_settings` manifest.json key.

Example
-------

```json
"dictionaries": {
  "en-US": "dictionaries/en-US.dic"
}
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


version_name - Mozilla

version\_name
=============

|  |  |
| --- | --- |
| Type | `String` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```json
"version\_name": "0.1 beta"
```
 |

In addition to the version field, which is used for update purposes, version\_name can be set to a descriptive version string and will be used for display purposes if present.

If no **version\_name** is present, the **version** field will be used for display purposes as well.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


version - Mozilla

version
=======

|  |  |
| --- | --- |
| Type | `String` |
| Mandatory | Yes |
| Example |
```json
"version": "0.1"
```
 |

The **version string** for the extension.

Version format
--------------

The version string consists of 1 to 4 numbers separated by dots, for example, `1.2.3.4`. Non-zero numbers must not include a leading zero. For example, `2.01` is not allowed; however, `0.2`, `2.0.1`, and `2.10` are allowed.

Extension stores and browsers may enforce or warn if the version string doesn't comply with this format. They may also apply restrictions to the range of numbers available. For example:

* addons.mozilla.org (AMO) allows version strings using numbers of up to nine digits, complying with this regular expression `^(0|[1-9][0-9]{0,8})([.](0|[1-9][0-9]{0,8})){0,3}$`. Also, from Firefox 108, a warning is provided if an extension is installed with a version number that doesn't match this format.
* The Chrome Web Store requires numbers between 0 and 65535 and does not permit all-zero extension strings. For example, 0.0 or 0.0.0.0 are not permitted.

It may be possible to create an extension that appears to have a valid version number when run in a browser but doesn't comply with store requirements. Particular care should be taken when developing cross-browser extensions that use large number elements.

Some browsers and web stores may recognize the version\_name key. This key enables you to provide a descriptive version string that may be displayed instead of the version number. For example, `1.0 beta`.

### Comparing versions

To determine which of two extension versions is the most recent, the version string numbers are compared left to right. A missing version string element is equivalent to `0`. For example, 1.0 is equivalent to 1.0.0.0. The first version string with a number greater than the corresponding number in the other version string is the most recent. For example, 1.10 is a more recent version than 1.9.

Legacy version formats
----------------------

See Legacy version formats for details of previously supported version strings.

Access the version number in code
---------------------------------

You obtain the extension version in your JavaScript code using:

```js
console.log(browser.runtime.getManifest().version);
```

If the manifest contains:

```json
"version": "0.1"
```

You see this in the console log:
```

"0.1"
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


content_scripts - Mozilla

content\_scripts
================

|  |  |
| --- | --- |
| Type | `Array` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```json
"content\_scripts": [
  {
    "matches": ["\*://\*.mozilla.org/\*"],
    "js": ["borderify.js"]
  }
]
```
 |

Instructs the browser to load content scripts into web pages whose URL matches a given pattern.

This key is an array. Each item is an object which:

* **must** contain a key named **`matches`**, which specifies the URL patterns to be matched in order for the scripts to be loaded;
* **may** contain keys named **`js`** and **`css`**, which list scripts and/or stylesheets to be loaded into matching pages; and
* **may** contain a number of other properties that control finer aspects of how and when content scripts are loaded.

Details of all the keys you can include are given in the table below.

| Name | Type | Description |
| --- | --- | --- |
| `all_frames` | `Boolean` |
`true`

 Inject the scripts specified in
 `js` and
 `css` into all frames matching the
 specified URL requirements, even if the frame is not the topmost
 frame in a tab. This does not inject into child frames where only
 their parent matches the URL requirements and the child frame does
 not match the URL requirements. The URL requirements are checked
 for each frame independently.

**Note:** This also applies to any tracker or ad
 that uses iframes, which means that enabling this could make
 your content script get called dozens of times on some pages.

`false`

 Inject only into frames matching the URL requirements which are the
 topmost frame in a tab.

Defaults to `false`. |
| `css` | `Array` |
 An array of paths, relative to `manifest.json`, referencing
 CSS files that will be injected into matching pages.

 Files are injected in the order given, and at the time specified by
 `run\_at`.

**Note:** Firefox resolves URLs in injected CSS files
 relative to the CSS file itself, rather than to the page it's
 injected into.

 |
| `exclude_globs` | `Array` |
 An array of strings containing wildcards. See
 Matching URL patterns below.
  |
| `exclude_matches` | `Array` |
 An array of
 match patterns. See Matching URL patterns below.
  |
| `include_globs` | `Array` |
 An array of strings containing wildcards. See
 Matching URL patterns below.
  |
| `js` | `Array` |
 An array of paths, relative to `manifest.json`, referencing
 JavaScript files that will be injected into matching pages.

 Files are injected in the order given. This means that, for example,
 if you include jQuery here followed by another content script, like
 this:

```json
"js": ["jquery.js", "my-content-script.js"]
```

Then, `"my-content-script.js"` can use jQuery.

 The files are injected after any files in
 `css`, and at the time specified by
 `run\_at`.
  |
| `match\_about\_blank` | `Boolean` |
 Insert the content scripts into pages whose URL is
 `"about:blank"` or `"about:srcdoc"`, if the URL
 of the page that opened or created this page
 matches the patterns specified in
 the rest of the `content_scripts` key.

 This is especially useful to run scripts in empty iframes, whose URL
 is `"about:blank"`. To do this you should also set the
 `all_frames` key.

 For example, suppose you have a `content_scripts` key like
 this:

```json
  "content\_scripts": [
    {
      "js": ["my-script.js"],
      "matches": ["https://example.org/"],
      "match\_about\_blank": true,
      "all\_frames": true
    }
  ]
```

 If the user loads `https://example.org/`, and this page
 embeds an empty iframe, then `"my-script.js"` will be
 loaded into the iframe.

**Note:** `match_about_blank` is supported
 in Firefox from version 52.

 Note that in Firefox, content scripts won't be injected into empty
 iframes at `"document_start"`, even if you specify that
 value in `run\_at` .

 |
| `matches` | `Array` |
 An array of
 match patterns. See
 Matching URL patterns below.

This is the only mandatory key. |
| `run_at` | `String` |
 This option determines when the files specified in
 `css` and
 `js` are injected. You can supply one of
 three strings here, each of which identifies a state in the process of
 loading a document. The states directly correspond to
 `Document.readyState`:

`"document_start"`
Corresponds to `loading`. The DOM is still loading.
`"document_end"`

 Corresponds to `interactive`. The DOM has finished
 loading, but resources such as scripts and images may still be
 loading.

`"document_idle"`

 Corresponds to `complete`. The document and all its
 resources have finished loading.

The default value is `"document_idle"`.

 In all cases, files in `js` are injected
 after files in `css`.
  |

Matching URL patterns
---------------------

The `"content_scripts"` key attaches content scripts to documents based on URL matching: if the document's URL matches the specification in the key, then the script will be attached. There are four properties inside `"content_scripts"` that you can use for this specification:

`matches`

an array of match patterns

`exclude_matches`

an array of match patterns

`include_globs`

an array of globs

`exclude_globs`

an array of globs

To match one of these properties, a URL must match at least one of the items in its array. For example, given a property like:

```json
"matches": ["\*://\*.example.org/\*", "\*://\*.example.com/\*"]
```

Both `http://example.org/` and `http://example.com/` will match.

Since `matches` is the only mandatory key, the other three keys are used to limit further the URLs that match. To match the key as a whole, a URL must:

* match the `matches` property
* AND match the `include_globs` property, if present
* AND NOT match the `exclude_matches` property, if present
* AND NOT match the `exclude_globs` property, if present
### globs

A *glob* is just a string that may contain wildcards.

There are two types of wildcard, and you can combine them in the same glob:

1. `*` matches zero or more characters
2. `?` matches exactly one character.

For example: `"*na?i"` would match `"illuminati"` and `"annunaki"`, but not `"sagnarelli"`.

Example
-------

```json
"content\_scripts": [
  {
    "matches": ["\*://\*.mozilla.org/\*"],
    "js": ["borderify.js"]
  }
]
```

This injects a single content script `borderify.js` into all pages under `mozilla.org` or any of its subdomains, whether served over HTTP or HTTPS.

```json
  "content\_scripts": [
    {
      "exclude\_matches": ["\*://developer.mozilla.org/\*"],
      "matches": ["\*://\*.mozilla.org/\*"],
      "js": ["jquery.js", "borderify.js"]
    }
  ]
```

This injects two content scripts into all pages under `mozilla.org` or any of its subdomains except `developer.mozilla.org`, whether served over HTTP or HTTPS.

The content scripts see the same view of the DOM and are injected in the order they appear in the array, so `borderify.js` can see global variables added by `jquery.js`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


optional_permissions - Mozilla

optional\_permissions
=====================

|  |  |
| --- | --- |
| Type | `Array` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```json
"optional\_permissions": [
  "webRequest"
]
```
 |

Use the `optional_permissions` key to list permissions that you want to ask for at runtime, after your extension has been installed.

The `permissions` key lists permissions that your extension needs before it can be installed. In contrast, `optional_permissions` lists permissions that your extension doesn't need at install time but it may ask for after it has been installed. To ask for a permission, use the `permissions` API. Asking for a permission may present the user with a dialog requesting them to grant the permission to your extension.

For advice on designing your request for runtime permissions, to maximize the likelihood that users grant them, see Request permissions at runtime.

Starting with Firefox 84, users will be able to manage optional permissions from the Firefox Add-ons Manager. Extensions that use optional permissions should listen for browser.permissions.onAdded and browser.permissions.onRemoved API events to know when a user grants or revokes these permissions.

The key can contain two kinds of permissions: host permissions and API permissions.

Host permissions
----------------

These are the same as the host permissions you can specify in the `permissions` key.

**Note:** When using Manifest V3 or higher:

* in Chrome, host permissions must be specified in the `host_permission` manifest key.
* in Firefox, during the Manifest V3 developer preview, hosts can be in either `host_permissions` or `optional_permissions`. Subject to completion of bug 1766026, hosts will be specified in either `host_permissions` or `optional_host_permissions`.

API permissions
---------------

You can include any of the following here, but not in all browsers: check the compatibility table for browser-specific details.

* `activeTab`
* `background`
* `bookmarks`
* `browserSettings`
* `browsingData`
* `clipboardRead`
* `clipboardWrite`
* `contentSettings`
* `contextMenus`
* `cookies`
* `debugger`
* `declarativeNetRequest`
* `declarativeNetRequestFeedback`
* `declarativeNetRequestWithHostAccess`
* `devtools`
* `downloads`
* `downloads.open`
* `find`
* `geolocation`
* `history`
* `idle`
* `management`
* `nativeMessaging`
* `notifications`
* `pageCapture`
* `pkcs11`
* `privacy`
* `proxy`
* `scripting`
* `sessions`
* `tabHide`
* `tabs`
* `topSites`
* `webNavigation`
* `webRequest`
* `webRequestBlocking`
* `webRequestFilterResponse`
* `webRequestFilterResponse.serviceWorkerScript`

Note that this is a subset of the API permissions allowed in `permissions`.

Of this set, the following permissions are granted silently, without a user prompt:

* `activeTab`
* `cookies`
* `idle`
* `webRequest`
* `webRequestBlocking`
* `webRequestFilterResponse`
* `webRequestFilterResponse.serviceWorkerScript`
Example
-------

```json
 "optional\_permissions": ["\*://developer.mozilla.org/\*"]
```

In Manifest V2 only, enable the extension to ask for privileged access to pages under developer.mozilla.org.

```json
  "optional\_permissions": ["tabs"]
```

Enable the extension to ask for access to the privileged pieces of the `tabs` API.

```json
  "optional\_permissions": ["\*://developer.mozilla.org/\*", "tabs"]
```

In Manifest V2 only, enable the extension to ask for both of the above permissions.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


short_name - Mozilla

short\_name
===========

|  |  |
| --- | --- |
| Type | `String` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```json
"short\_name": "My Extension"
```
 |

Short name for the extension. If given, this will be used in contexts where the name field is too long. It's recommended that the short name should not exceed 12 characters. If the short name field is not included in manifest.json, then name will be used instead and may be truncated.

This is a localizable property.

Example
-------

```json
"short\_name": "My Extension"
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


user_scripts - Mozilla

user\_scripts
=============

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory | No |
| Manifest version | 2 |
| Example |
```json
  "user\_scripts": {
    "api\_script": "apiscript.js",
  }
```

 |

Instructs the browser to load a script packaged in the extension, known as the API script, this script is used to export a set of custom API methods for use in user scripts. The API script path, relative to the manifest.json file, is defined as a `string` in `"api_script"`.

**Note:** The `user_script` key is required for the `userScripts` API to function, even if no API script is specified. For example. `user_scripts: {}`.

The API script:

* runs in the content processes.
* has access to the window and document globals related to the webpage it is attached to.
* has access to the same subset of WebExtension APIs usually available in a content script.

The script executes automatically on any webpage defined in `matches` by `userScripts.register`. However, this is before the user script sandbox object is created and the custom API methods can be exported.

To export the custom API methods, the script listens for `userScripts.onBeforeScript` and then export the custom API methods.

Not every user script may need to consume all of the custom API methods. You can, therefore, include details of the APIs needed in `scriptMetadata` when running `userScripts.register`. The API script then accesses the `scriptMetadata` through the `script` parameter received by the `userScripts.onBeforeScript` listener (as `script.metadata`).

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `userScripts`
* `contentScripts`


externally_connectable - Mozilla

externally\_connectable
=======================

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```
"externally_connectable": {
  "ids": [
    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "cccccccccccccccccccccccccccccccc"
  ],
  "matches": [
    "https://example1.com/*",
    "*://*.example2.com/*"
  ]
}
```
 |

Externally connectable controls which other extensions and web pages can communicate with an extension using `runtime.connect()` and `runtime.sendMessage()` message passing. If `externally_connectable` is not specified, all extensions can communicate with each other but not with web pages.

**Note:**
 For communication with web pages:

* In Chrome, `chrome.runtime.connect` and `chrome.runtime.sendMessage` are used. These methods are only available when there is at least one extension listening for messages, see chrome.runtime will no longer be defined unconditionally in Chrome 106 for more details.
* In Safari, `browser.runtime.connect` and `browser.runtime.sendMessage` are used.
* In Firefox, neither API is supported. See Firefox bug 1319168.

### "ids" attribute

`ids` enables communication between this extension and other installed extensions specified by extension identifiers. Use the pattern `"*"` to communicate with all extensions.

### "matches" attribute

`matches` is a list of regular expressions that enables communication between an extension and the web pages that match the expression.

**Note:** If `externally_connectable` is not specified, communication among extensions is allowed as if `externally_connectable` specified `{"ids": ["*"] }`. Therefore, if you specify `externally_connectable.matches`, don't forget to add `ids` if you want to communicate with other extensions.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


action - Mozilla

action
======

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory | No |
| Manifest version | 3 or higher |
| Example |
```json
"action": {
  "default\_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default\_title": "Whereami?",
  "default\_popup": "popup/geo.html",
  "theme\_icons": [{
    "light": "icons/geo-16-light.png",
    "dark": "icons/geo-16.png",
    "size": 16
  }, {
    "light": "icons/geo-32-light.png",
    "dark": "icons/geo-32.png",
    "size": 32
  }]
}
```
 |

An action is a button that your extension adds to the browser's toolbar. The button has an icon, and may optionally have a popup whose content is specified using HTML, CSS, and JavaScript.

This key replaces `browser_action` in Manifest V3 extensions.

If you supply a popup, then the popup is opened when the user clicks the button, and your JavaScript running in the popup can handle the user's interaction with it. If you don't supply a popup, then a click event is dispatched to your extension's background scripts when the user clicks the button.

You can also create and manipulate actions programmatically using the `action` .

Syntax
------

The `action` key is an object that may have any of these properties, all optional:

| Name | Type | Description |
| --- | --- | --- |
| `browser\_style`Optional
Deprecated
 | `Boolean` | Optional, defaulting to `false`.

Do not set `browser_style` to true: its support in Manifest V3 was removed in Firefox 118. See Manifest V3 migration for `browser_style`.
 |
| `default_area`Optional | `String` |
 Defines the part of the browser in which the button is initially
 placed. This is a string that may take one of four values:
 * "navbar": the button is placed in the main browser toolbar,
 alongside the URL bar.
* "menupanel": the button is placed in a popup panel.
* "tabstrip": the button is placed in the toolbar that contains
 browser tabs.
* "personaltoolbar": the button is placed in the bookmarks toolbar.

This property is only supported in Firefox.
This property is optional, and defaults to "menupanel".

 Firefox remembers the `default_area` setting for an
 extension, even if that extension is uninstalled and subsequently
 reinstalled. To force the browser to acknowledge a new value for
 `default_area`, the id of the extension must be changed.

 An extension can't change the location of the button after it has been
 installed, but the user may be able to move the button using the
 browser's built-in UI customization mechanism.
  |
| `default_icon`Optional | `Object` or `String` |
 Use this to specify one or more icons for the action. The icon
 is shown in the browser toolbar by default.

Icons are specified as URLs relative to the manifest.json file itself.
You can specify a single icon file by supplying a string here:

```json
"default\_icon": "path/to/geo.svg"
```

 To specify multiple icons in different sizes, specify an object here.
 The name of each property is the icon's height in pixels, and must be
 convertible to an integer. The value is the URL. For example:

```json
    "default\_icon": {
      "16": "path/to/geo-16.png",
      "32": "path/to/geo-32.png"
    }
```

 You cannot specify multiple icons of the same sizes.See
 Choosing icon sizes
 for more guidance on this.
  |
| `default_popup`Optional | `String` | The path to an HTML file containing the specification of the popup.

 The HTML file may include CSS and JavaScript files using
 `<link>`
 and
 `<script>`
 elements, just like a normal web page. However,
 `<script>`must have
 `src`
 attribute to load a file. Don't use
 `<script>`
 with embedded code, because you'll get a confusing Content Violation
 Policy error.

 Unlike a normal web page, JavaScript running in the popup can access
 all the
 WebExtension APIs
 (subject, of course, to the extension having the appropriate
 permissions).

 This is a
 localizable property.
  |
| `default_title`Optional | `String` |
 Tooltip for the button, displayed when the user moves their mouse over
 it. If the button is added to the browser's menu panel, this is also
 shown under the app icon.

 This is a
 localizable property.
  |
| `theme_icons`Optional | `Array` |
 This property enables you to specify different icons for themes
 depending on whether Firefox detects that the theme uses dark or light
 text.

 If this property is present, it's an array containing at least one
 `ThemeIcons` object. A `ThemeIcons` object
 contains three mandatory properties:

`"dark"`

 A URL pointing to an icon. This icon displays when a theme using
 dark text is active (such as the Firefox Light theme, and the
 Default theme if no default\_icon is specified).

`"light"`

 A URL pointing to an icon. This icon displays when a theme using
 light text is active (such as the Firefox Dark theme).

`"size"`
The size of the two icons in pixels.

Icons are specified as URLs relative to the manifest.json file.

 You should supply 16x16 and 32x32 (for retina display)
 `ThemeIcons`.
  |

Choosing icon sizes
-------------------

The action's icon may need to be displayed in different sizes in different contexts:

* The icon is displayed in the browser toolbar. Older versions of Firefox supported the option of placing the icon in the browser's menu panel (the panel that opens when the user clicks the "hamburger" icon). In those versions of Firefox the icon in the menu panel was larger than the icon in the toolbar.
* On a high-density display like a Retina screen, icons needs to be twice as big.

If the browser can't find an icon of the right size in a given situation, it will pick the best match and scale it. Scaling may make the icon appear blurry, so it's important to choose icon sizes carefully.

There are two main approaches to this. You can supply a single icon as an SVG file, and it will be scaled correctly:

```json
"default\_icon": "path/to/geo.svg"
```

Alternatively, you can supply several icons in different sizes, and the browser will pick the best match.

In Firefox:

* The default height and width for icons in the toolbar is 16 \* `window.devicePixelRatio`.
* The default height and width for icons in the menu panel is 32 \* `window.devicePixelRatio`.

So you can specify icons that match exactly, on both normal and Retina displays, by supplying three icon files, and specifying them like this:

```json
"default\_icon": {
  "16": "path/to/geo-16.png",
  "32": "path/to/geo-32.png",
  "64": "path/to/geo-64.png"
}
```

If Firefox can't find an exact match for the size it wants, then it will pick the smallest icon specified that's bigger than the ideal size. If all icons are smaller than the ideal size, it will pick the biggest icon specified.

Example
-------

```json
"action": {
  "default\_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  }
}
```

An action with just an icon, specified in 2 sizes. The extension's background scripts can receive click events when the user clicks the icon using code like this:

```js
browser.action.onClicked.addListener(handleClick);
```

```json
"action": {
  "default\_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default\_title": "Whereami?",
  "default\_popup": "popup/geo.html"
}
```

An action with an icon, a title, and a popup. The popup is shown when the user clicks the button.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


host_permissions - Mozilla

host\_permissions
=================

|  |  |
| --- | --- |
| Type | `Array` |
| Mandatory | No |
| Manifest version | 3 or higher |
| Example |
```json
"host\_permissions": [
  "\*://developer.mozilla.org/\*",
  "\*://\*.example.org/\*"
]
```
 |

Use the `host_permissions` key to request access for the APIs in your extension that read or modify host data, such as `cookies`, `webRequest`, and `tabs`. This key is an array of strings, and each string is a request for a permission.

### Requested permissions and user prompts

Most browsers treat `host_permission` as optional. If you request permissions using this key, users *may* get prompted to grant those permissions during installation. As of June 2023, Safari, Firefox, and some Chromium-based browsers don't prompt the user during installation.

Users can also grant or revoke host permissions on an ad hoc basis. For example, in Firefox, users can do this using the extensions panel.

Your extension can check whether it has all the required permissions immediately after installation using `permissions.contains`. If it doesn't have the necessary permissions, it can request them using `permissions.request`. Providing an onboarding step to explain why some permissions are necessary before requesting them might also be helpful.

As the request to grant host permissions may impact users' willingness to install your extension, requesting host permissions is worth careful consideration. For example, you want to avoid requesting unnecessary host permissions and may want to provide information about why you are requesting host permissions in your extension's store description. The article Request the right permissions provides more information on the issues you should consider.

For information on how to test and preview permission requests, see Test permission requests on the Extension Workshop site.

### Format

Host permissions are specified as match patterns, and each pattern identifies a group of URLs for which the extension is requesting extra privileges. For example, a host permission could be `"*://developer.mozilla.org/*"`.

The extra privileges include:

* XMLHttpRequest and fetch access to those origins without cross-origin restrictions (though not for requests from content scripts, as was the case in Manifest V2).
* the ability to read tab-specific metadata without the "tabs" permission, such as the `url`, `title`, and `favIconUrl` properties of `tabs.Tab` objects.
* the ability to inject scripts programmatically (using `tabs.executeScript()`) into pages served from those origins.
* the ability to receive events from the `webrequest` API for these hosts.
* the ability to access cookies for that host using the `cookies` API, as long as the `"cookies"` API permission is also included.
* bypassing tracking protection for extension pages where a host is specified as a full domain or with wildcards.

In Firefox extensions get host permissions for their origin, which is of the form:

```url
moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/
```

where `60a20a9b-1ad4-af49-9b6c-c64c98c37920` is the extension's internal ID. The extension can get this URL programmatically by calling `extension.getURL()`:

```js
browser.extension.getURL("");
// moz-extension://60a20a9b-1ad4-af49-9b6c-c64c98c37920/
```

Example
-------

```json
 "host\_permissions": ["\*://developer.mozilla.org/\*"]
```

Request privileged access to pages under `developer.mozilla.org`.

Example extensions
------------------

* dnr-redirect-url
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


description - Mozilla

description
===========

|  |  |
| --- | --- |
| Type | `String` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```json
"description": "Replaces pictures with pictures of cats."
```
 |

A short description of the extension, intended for display in the browser's user interface. In Firefox and Chrome this value can be up to 132 characters. The limit in other browsers may differ.

This is a localizable property.

Example
-------

```json
"description": "Replaces pictures with pictures of cats."
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


web_accessible_resources - Mozilla

web\_accessible\_resources
==========================

|  |  |
| --- | --- |
| Type | `Array` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```json
"web\_accessible\_resources": [
  "images/my-image.png"
]
```
 |

Description
-----------

Sometimes you want to package resources—for example, images, HTML, CSS, or JavaScript—with your extension and make them available to web pages and other extensions.

**Note:** Until Firefox 105, extensions could access resources packaged in other extensions by default. From Firefox 105 onwards, to enable other extensions to access an extension's resources they must be included in this key.

For example, the Beastify example extension replaces a web page with an image of a beast selected by the user. The beast images are packaged with the extension. To make the selected image visible, the extension adds `<img>` elements whose `src` attribute points to the beast's image. For the web page to be able to load the images, they must be made web accessible.

With the `web_accessible_resources` key, you list all the packaged resources that you want to make available to web pages. You specify them as paths relative to the manifest.json file.

Note that content scripts don't need to be listed as web accessible resources.

If an extension wants to use `webRequest` or `declarativeNetRequest` to redirect a public URL (e.g., HTTPS) to a page that's packaged in the extension, then the extension must list the page in the `web_accessible_resources` key.

### Manifest V2 syntax

In Manifest V2, web accessible resources are added as an array under the key, like this:

```json
"web\_accessible\_resources": [
  "images/my-image.png"
]
```

### Manifest V3 syntax

In Manifest V3, the `web_accessible_resources` key is an array of objects like this:

```json
{
  // …
  "web\_accessible\_resources": [
    {
      "resources": ["test1.png", "test2.png"],
      "matches": ["https://web-accessible-resources-1.glitch.me/\*"]
    },
    {
      "resources": ["test3.png", "test4.png"],
      "matches": ["https://web-accessible-resources-2.glitch.me/\*"],
      "use\_dynamic\_url": true
    }
  ]
  // …
}
```

Each object must include a `"resources"` property and either a `"matches"` or `"extension_ids"` property from the following properties:

| Name | Type | Description |
| --- | --- | --- |
| `extension_ids` | `Array` of `String` | Optional. Defaults to `[]`, meaning that other extensions cannot access the resource.

 A list of extension IDs specifying the extensions that can access the resources.
 "\*" matches all extensions.
  |
| `matches` | `Array` of `String` | Optional. Defaults to `[]`, meaning that other websites cannot access the resource.
 A list of URL match patterns specifying the pages that can access the resources. Only the origin is used to match URLs. Origins include subdomain matching. Paths must be set to `/*`. |
| `resources` | `Array` of `String` | An array of resources to be exposed. Resources are specified as strings and may contain `*` for wildcard matches. For example, `"/images/*"` exposes everything in the extension's `/images` directory recursively, while `"*.png"` exposes all PNG files. |
| `use_dynamic_url` | `Boolean` | Optional. Defaults to `false`.
 Whether resources to be accessible through the dynamic ID. The dynamic ID is generated per session and regenerated on browser restart or extension reload. |

### Using web\_accessible\_resources

Suppose your extension includes an image file at `images/my-image.png`, like this:
```

my-extension-files/
    manifest.json
    my-background-script.js
    images/
        my-image.png
```

To enable a web page to use an `<img>` element whose `src` attribute points to this image, you would specify `web_accessible_resources` like this:

```json
"web\_accessible\_resources": ["images/my-image.png"]
```

The file is then available using a URL like:
```

moz-extension://<extension-UUID>/images/my-image.png"
```

`<extension-UUID>` is **not** your extension's ID. This ID is randomly generated for every browser instance. This prevents websites from fingerprinting a browser by examining the extensions it has installed.

**Note:** In Chrome in Manifest V2, an extension's ID is fixed. When a resource is listed in `web_accessible_resources`, it is accessible as `chrome-extension://<your-extension-id>/<path/to/resource>`. In Manifest V3, Chrome can use a dynamic URL by setting `use_dynamic_url` to `true`.

The recommended approach to obtaining the URL of the resource is to use `runtime.getURL` passing the path relative to manifest.json, for example:

```js
browser.runtime.getURL("images/my-image.png");
// something like:
// moz-extension://944cfddf-7a95-3c47-bd9a-663b3ce8d699/images/my-image.png
```

This approach gives you the correct URL regardless of the browser your extension is running on.

### Wildcards

`web_accessible_resources` entries can contain wildcards. For example, the following entry would also work to include the resource at "images/my-image.png":

```json
  "web\_accessible\_resources": ["images/\*.png"]
```

### Security

If you make a page web-accessible, any website may link or redirect to that page. The page should then treat any input (POST data, for example) as if it came from an untrusted source, just as a normal web page should.

Web-accessible extension resources are not blocked by CORS or CSP. Because of this ability to bypass security checks, extensions should avoid using web-accessible scripts when possible. A web-accessible extension script can unexpectedly be misused by malicious websites to weaken the security of other websites. Follow the security best practices by avoiding injection of moz-extension:-URLs in web pages and ensuring that third-party libraries are up to date.

Example
-------

### Manifest V2 example

```json
"web\_accessible\_resources": ["images/my-image.png"]
```

Make the file at "images/my-image.png" web accessible to any website and extension.

### Manifest V3 example

```json
"web\_accessible\_resources": [
  {
    "resources": [ "images/my-image.png" ],
    "extension\_ids": ["\*"],
    "matches": [ "\*://\*/\*" ]
  }
]
```

Make the file at "images/my-image.png" web accessible to any website and extension.

 It is recommended to only specify `extension_ids` or `matches` if needed.
 For example, if the resource only needs to be accessible to web pages at example.com:

```json
"web\_accessible\_resources": [
  {
    "resources": [ "images/my-image.png" ],
    "matches": [ "https://example.com/\*" ]
  }
]
```

Example extensions
------------------

* beastify
* dnr-redirect-url
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


background - Mozilla

background
==========

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```json
"background": {
  "scripts": ["background.js"]
}
```
 |

Use the `background` key to include one or more background scripts, a background page, or a Service worker in your extension.

Background scripts are the place to put code that needs to maintain a long-term state or perform long-term operations independently of the lifetime of any particular web pages or browser windows.

Background scripts are loaded as soon as the extension is loaded and stay loaded until the extension is disabled or uninstalled unless `persistent` is specified as `false`. You can use any WebExtension APIs in the script if you have requested the necessary permissions.

See Background scripts for some more details.

The `background` key is an object that must have one of these properties (for more information on how these properties are supported, see Browser support):

|  |  |
| --- | --- |
| `page` |
 If you need specific content in the background page, you can define a
 page using the `page` property. This is a
 `String` representing a path relative to the manifest.json
 file to an HTML document included in your extension bundle.

 If you use this property, you can not specify background scripts using
 `scripts`, but you can include scripts from the
 page, just like a normal web page.
  |
| `scripts` |
 An `Array` of `Strings`, each of which is a path
 to a JavaScript source. The path is relative to the manifest.json file
 itself. These are the scripts that are executed in the
 extension's background page.

The scripts share the same `window` global context.
The scripts are loaded in the order they appear in the array.

 If you specify `scripts`, an empty page
 is created where your scripts run.

**Note:** If you want to fetch a script from a remote
 location with the `<script>` tag (e.g.,
 `<script src =
"https://code.jquery.com/jquery-3.6.0.min.js">`), you have to change the
 `content\_security\_policy`
 key in the manifest.json file of your extension.

 |
| `service_worker` | Specify a JavaScript file as the extension service worker. A service worker is a background script that acts as the extension's main event handler. |

The `background` key can also contain this optional property:

|  |  |
| --- | --- |
| `persistent` | A `Boolean` value.
If omitted, this property defaults to `true` in Manifest V2 and `false` in Manifest V3. Setting to `true` in Manifest V3 results in an error.* `true` indicates the background page is to be kept in
 memory from when the extension is loaded or the browser starts until
 the extension is unloaded or disabled, or the browser is closed
 (that is, the background page is persistent).
* `false` indicates the background page may be unloaded
 from memory when idle and recreated when needed. Such background
 pages are often called Event Pages, because they are loaded into
 memory to allow the background page to handle the events to which it
 has added listeners. Registration of listeners is persistent when
 the page is unloaded from memory, but other values are not
 persistent. If you want to store data persistently in an event page,
 then you should use the
 storage API.
 |
| `type` | A `String` value.
Determines whether the scripts specified in `"scripts"` are loaded as ES modules.* `classic` indicates the background scripts or service workers are not included as an ES Module.
* `module` indicates the background scripts or service workers are included as an ES Module. This enables the background page or service worker to `import` code.

If omitted, this property defaults to `classic`. |

Browser support
---------------

Support for the `scripts`, `page`, and `service_worker` properties varies between browsers like this:

* Chrome:
    + supports `background.service_worker`.
    + supports `background.scripts` (and `background.page`) in Manifest V2 extensions only.
    + before Chrome 121, Chrome refuses to load a Manifest V3 extension with `background.scripts` or `background.page` present. From Chrome 121, their presence in a Manifest V3 extension is ignored.
* Firefox:
    + `background.service_worker` is not supported (see Firefox bug 1573659).
    + supports `background.scripts` (or `background.page`) if `service_worker` is not specified or the service worker feature is disabled. Before Firefox 120, Firefox did not start the background page if `service_worker` was present (see Firefox bug 1860304). From Firefox 121, the background page starts as expected, regardless of the presence of `service_worker`.
* Safari:
    + supports `background.service_worker`.
    + supports `background.scripts` (or `background.page`) if `service_worker` is not specified.

To illustrate, this is a simple example of a cross-browser extension that supports `scripts` and `service_worker`. The example has this manifest.json file:

```json
{
  "name": "Demo of service worker + event page",
  "version": "1",
  "manifest\_version": 3,
  "background": {
    "scripts": ["background.js"],
    "service\_worker": "background.js"
  }
}
```

And, background.js contains:

```javascript
if (typeof browser == "undefined") {
  // Chrome does not support the browser namespace yet.
  globalThis.browser = chrome;
}
browser.runtime.onInstalled.addListener(() => {
  browser.tabs.create({ url: "http://example.com/firstrun.html" });
});
```

When the extension is executed, this happens:

* in Chrome, the `service_worker` property is used, and a service worker starts that opens the tab because, in a Manifest V3 extension, Chrome only supports service workers for background scripts.
* in Firefox, the `scripts` property is used, and a script starts that opens the tab because Firefox only supports scripts for background scripts.
* in Safari, the `service_worker` property is used, and a service worker starts that opens the tab because Safari gives priority to using service workers for background scripts.
Examples
--------

```json
  "background": {
    "scripts": ["jquery.js", "my-background.js"]
  }
```

Load two background scripts.

```json
  "background": {
    "page": "my-background.html"
  }
```

Load a custom background page.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


homepage_url - Mozilla

homepage\_url
=============

|  |  |
| --- | --- |
| Type | `String` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```json
"homepage\_url": "https://example.org/my-addon"
```
 |

URL for the extension's home page.

 If a developer key containing the "url" property and "homepage\_url" are defined, Firefox uses "developer.url" while Opera uses "homepage\_url".
 Chrome and Safari do not support the "developer" key.

This is a localizable property.

Example
-------

```json
"homepage\_url": "https://github.com/mdn/webextensions-examples/tree/main/beastify"
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


offline_enabled - Mozilla

offline\_enabled
================

|  |  |
| --- | --- |
| Type | `Boolean` |
| Mandatory | No |
| Manifest version | 2 |
| Example |
```json
"offline\_enabled": true
```
 |

**Non-standard:** This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

Whether the app or extension is expected to work offline. When Chrome detects that it is offline, apps with this field set to true will be highlighted on the New Tab page.

As of Chrome 35, apps (ChromeOS only from 2018) are assumed to be offline enabled and the default value of `"offline_enabled"` is `true` unless `"webview"` permission is requested. In this case, network connectivity is assumed to be required and `"offline_enabled"` defaults to `false`.

The `"offline_enabled"` value is also used to determine whether a network connectivity check will be performed when launching an app in ChromeOS kiosk mode. A network connectivity check will be performed when apps are not offline enabled, and app launching put on hold until the device obtains connectivity to the Internet.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


browser_specific_settings - Mozilla

browser\_specific\_settings
===========================

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory |
 Usually, no (but see also
 When do you need an Add-on ID?). Mandatory if the extension ID cannot be determined, see
 `browser_specific_settings.gecko.id`.
  |
| Example |
```json
"browser\_specific\_settings": {
  "gecko": {
    "id": "addon@example.com",
    "strict\_min\_version": "42.0"
  }
}
```

 |

Description
-----------

The `browser_specific_settings` key contains keys that are specific to a particular host application.

### Firefox (Gecko) properties

Firefox stores browser-specific settings in these sub-keys:

* `gecko` for the desktop version of Firefox.
* `gecko_android` for the Android version of Firefox.

The `gecko` subkey supports these properties:

`id`

The extension ID. When provided, this property must contain 80 characters or less. See Extensions and the Add-on ID to determine when to specify the ID.

`strict_min_version`

Minimum version of Gecko to support. If the Firefox version on which the extension is being installed or run is below this version, the extension is not installed or not run. If not provided, all versions earlier than `strict_max_version` are supported. "\*" is not valid in this field.

`strict_max_version`

Maximum version of Gecko to support. If the Firefox version on which the extension is being installed or run is above this version, the extension is not installed or not run. Defaults to "\*", which disables checking for a maximum version.

`update_url`

A link to an extension update manifest. Note that the link must begin with "https". This key is for managing extension updates yourself (i.e., not through AMO).

The `gecko_android` subkey supports these properties:

`strict_min_version`

Minimum version of Gecko to support on Android. If the Firefox for Android version on which the extension is being installed or run is below this version, the extension is not installed or not run. If not provided, defaults to the version determined by `gecko.strict_min_version`. "\*" is not valid in this field.

`strict_max_version`

Maximum version of Gecko to support on Android. If the Firefox version on which the extension is being installed or run is above this version, the extension is not installed or not run. Defaults to the version determined by `gecko.strict_max_version`.

See the list of valid Gecko versions.

#### Extension ID format

The extension ID must be one of the following:

* GUID
* A string formatted like an email address: `extensionname@example.org`

The latter format is easier to generate and manipulate. Be aware that using a real email address here may attract spam.

For example:

```json
"id": "extensionname@example.org"
```

```json
"id": "{daf44bf7-a45e-4450-979c-91cf07434c3d}"
```

### Safari properties

Safari stores its browser-specific settings in the `safari` subkey, which has these properties:

`strict_min_version`

Minimum version of Safari to support.

`strict_max_version`

Maximum version of Safari to support.

Examples
--------

Example with all possible keys. Note that most extensions omit `strict_max_version` and `update_url`.

```json
"browser\_specific\_settings": {
  "gecko": {
    "id": "addon@example.com",
    "strict\_min\_version": "42.0",
    "strict\_max\_version": "50.\*",
    "update\_url": "https://example.com/updates.json"
  },
  "safari": {
    "strict\_min\_version": "14",
    "strict\_max\_version": "20"
  }
}
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


options_ui - Mozilla

options\_ui
===========

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```json
"options\_ui": {
  "page": "options/options.html"
}
```
 |

Use the `options_ui` key to define an options page for your extension.

The options page contains settings for the extension. The user can access it from the browser's add-ons manager, and you can open it from within your extension using `runtime.openOptionsPage()`.

You specify `options_ui` as a path to an HTML file packaged with your extension. The HTML file can include CSS and JavaScript files, just like a normal web page. Unlike a normal page, though, the JavaScript can use all the WebExtension APIs that the extension has permissions for. However, it runs in a different scope than your background scripts.

 If you want to **share** data or functions between the JavaScript on your **options page** and your **background script(s)**, you can do so directly by obtaining a reference to the Window of your background scripts by using `extension.getBackgroundPage()`, or a reference to the `Window` of any of the pages running within your extension with `extension.getViews()`. Alternately, you can communicate between the JavaScript for your options page and your background script(s) using `runtime.sendMessage()`, `runtime.onMessage`, or `runtime.connect()`.
 The latter (or `runtime.Port` equivalents) can also be used to share options between your background script(s) and your **content script(s).**

In general, you will want to store options changed on option pages using the storage API to either `storage.sync` (if you want the settings synchronized across all instances of that browser that the user is logged into), or `storage.local` (if the settings are local to the current machine/profile). If you do so and your background script(s) (or content script(s)) need to know about the change, your script(s) might choose to add a listener to `storage.onChanged`.

Syntax
------

The `options_ui` key is an object with the following contents:

| Name | Type | Description |
| --- | --- | --- |
| `browser\_style`Optional
Deprecated
 in Manifest V3. | `Boolean` | Optional, defaulting to:* `true` in Manifest V2 and prior to Firefox 115 in Manifest V3.
* `false` in Manifest V3 from Firefox 115.

Do not set `browser_style` to true: its not support in Manifest V3 from Firefox 118. See Manifest V3 migration for `browser_style`.

 In Firefox, the stylesheet can be seen at
 `chrome://browser/content/extension.css` or
 `chrome://browser/content/extension-mac.css` on macOS. When
 setting dimensions, be aware that this stylesheet sets
 `box-sizing: border-box` (see
 box-sizing).
  |
| `open_in_tab`Optional | `Boolean` | Defaults to `false`.

 If `true`, the options page will open in a normal browser
 tab, rather than being integrated into the browser's add-ons manager.
  |
| `page` | `String` | Mandatory.

 The path to an HTML file containing the specification of your options
 page.

 The path is relative to the location of
 `manifest.json` itself.
  |

Example
-------

```json
"options\_ui": {
  "page": "options/options.html"
}
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `options_page`
Deprecated
* Browser styles
* Options pages


developer - Mozilla

developer
=========

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```json
"developer": {
  "name": "Walt Whitman",
  "url": "https://en.wikipedia.org/wiki/Walt\_Whitman"
}
```
 |

The name of the extension's developer and their homepage URL, intended for display in the browser's user interface.

The object, and both of its properties, are optional. The "name" and "url" properties, if present, will override the author and homepage\_url keys, respectively. This object only allows for a single developer name and URL to be specified.

This is a localizable property.

Example
-------

```json
"developer": {
  "name": "Walt Whitman",
  "url": "https://en.wikipedia.org/wiki/Walt\_Whitman"
}
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


default_locale - Mozilla

default\_locale
===============

|  |  |
| --- | --- |
| Type | `String` |
| Mandatory |
 Contingent: must be present if the \_locales subdirectory is present,
 must be absent otherwise.
  |
| Example |
```json
"default\_locale": "en"
```
 |

This key must be present if the extension contains the \_locales directory, and must be absent otherwise. It identifies a subdirectory of \_locales, and this subdirectory will be used to find the default strings for your extension.

See Internationalization.

Example
-------

```json
"default\_locale": "en"
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


name - Mozilla

name
====

|  |  |
| --- | --- |
| Type | `String` |
| Mandatory | Yes |
| Example |
```json
"name": "My Extension"
```
 |

Name of the extension. This is used to identify the extension in the browser's user interface and on sites like addons.mozilla.org.

It's good practice to keep the name short enough to display in the UI. Google Chrome and Microsoft Edge restrict the name length to 45 characters.

This is a localizable property.

Example
-------

```json
"name": "My Extension"
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


omnibox - Mozilla

omnibox
=======

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example |
```json
"omnibox": {
  "keyword": "mdn"
}
```
 |

Use the `omnibox` key to define an omnibox keyword for your extension.

When the user types this keyword into the browser's address bar, followed by a space, then any subsequent characters will be sent to the extension using the `omnibox` API. The extension will then be able to populate the address bar's drop-down suggestions list with its own suggestions.

If two or more extensions define the same keyword, then the extension that was installed last gets to control the keyword. Any previously installed extensions that defined the same keyword will no longer be able to use the `omnibox` API.

Example
-------

```json
"omnibox": {
  "keyword": "mdn"
}
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.