Docs4dev
Docs
web_extensions / latest / user_interface / browser_styles.html

Browser styles

Certain user interface components - browser and page action popups, sidebars, and options pages - are specified by your extension in essentially the same way:

  1. create an HTML file defining the structure of the UI element
  2. add a manifest.json key (browser_action, page_action, sidebar_action, or options_ui) pointing to that HTML file.

One of the challenges with this approach is styling the element in such a way that it fits in with the browser's own style. To help with this, the manifest.json keys include an extra optional property: browser_style. If this is included and set to true, then your document will get one or more extra stylesheets that will help make it look consistent with the browser's UI and with other extensions that use the browser_style property.

When considering using browser_style: true, you need to test your extension with various themes (built-in or from AMO) to make sure that the extension UI behaves the way you expect it to.

Warning: When browser_style: true is included in your web extension's manifest, text selection in your extension's UI is disabled except in input controls. If this will cause a problem, include browser_style:false instead.

Note: Google Chrome and Opera use chrome_style instead of browser_style, so if you wish to support them, you need to add both keys.

In Firefox, the stylesheet can be seen at chrome://browser/content/extension.css. The extra stylesheet at chrome://browser/content/extension-mac.css is also included on macOS.

Most styles are automatically applied, but some elements require you to add the non-standard browser-style class to get their styling, as detailed in the table below:

Element Example
<button> 
<button class="browser-style">Click me</button>

<select>

 
<select class="browser-style" name="select">
  <option value="value1">Value 1</option>
  <option value="value2" selected>Value 2</option>
  <option value="value3">Value 3</option>
</select>
<textarea> 
<textarea class="browser-style">Write here</textarea>
Parent of an <input> 
<div class="browser-style">
  <input type="radio" id="op1" name="choices" value="op1"/>
  <label for="op1">Option 1</label>
<input type="radio" id="op2" name="choices" value="op2"/>
<label for="op2">Option 2</label>
</div>

Note: See Firefox bug 1465256 for removal of this unnecessary requirement.

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
Browser_styles 40 79 48 ? 27 14 ? ? 57 ? 15 ?
browser_style 40 79 55 ? 27 No ? ? 57 ? No ?
open_in_tab 40 79 48 ?
NoOptions pages are always opened in a separate browser tab.
NoOptions pages are always opened in a separate browser tab.
? ? 57 ?
NoOptions pages are always opened in a separate browser tab.
?
page 40 79 48 ? 27 14 ? ? 57 ? 15 ?
Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
Browser_styles No No 54 ? 30 No ? ? No ? No ?
browser_style No No 55 ? No No ? ? No ? No ?
default_icon No No 54 ?
30SVG icons are not supported.
No ? ? No ? No ?
default_panel No No 54 ? 30 No ? ? No ? No ?
default_title No No 54 ? 30 No ? ? No ? No ?
open_at_install No No 62 ? No No ? ? No ? No ?
Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
Browser_styles
Yes["Since Chrome 49, page actions are displayed on the toolbar, rather than in the address bar.", "If an extension defines a page action, it is not allowed to define a browser action as well."]
14 48 ?
YesIf an extension defines a page action, it is not allowed to define a browser action as well.
14If an extension defines a page action, it is not allowed to define a browser action as well.
? ? Yes ?
15If an extension defines a page action, it is not allowed to define a browser action as well.
?
browser_style No No 48 ? No No ? ? No ? No ?
default_icon
YesSVG icons are not supported.
14["SVG icons are not supported.", "'default_icon' must be an object, with explicit sizes."]
48 ?
YesSVG icons are not supported.
14SVG icons are not supported. Grayscale images will be treated as template icons and processed with the system accent color and system appearance.
? ? Yes ?
15SVG icons are not supported. Grayscale images will be treated as template icons and processed with the system accent color and system appearance.
?
default_popup Yes 14 48 ? Yes 14 ? ? Yes ? 15 ?
default_title Yes 14 48 ? Yes 14 ? ? Yes ? 15 ?
hide_matches No No 59 ? No No ? ? 59 ? No ?
pinned No No 64 ? No No ? ? No ? No ?
show_matches No No 59 ? No No ? ? 79 ? No ?
Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
Browser_styles
Yes["Available for use in Manifest V2 only.", "If an extension defines a browser action, it is not allowed to define a page action as well."]
14Available for use in Manifest V2 only.
48Available for use in Manifest V2 only.
?
Yes["Available for use in Manifest V2 only.", "If an extension defines a browser action, it is not allowed to define a page action as well."]
14["Available for use in Manifest V2 only.", "If an extension defines a browser action, it is not allowed to define a page action as well."]
? ?
55Available for use in Manifest V2 only.
?
15["Available for use in Manifest V2 only.", "If an extension defines a browser action, it is not allowed to define a page action as well."]
?
browser_style No No 48 ? No No ? ? No ? No ?
default_area No No 54 ? No No ? ? No ? No ?
default_icon
YesSVG icons are not supported.
14["SVG icons are not supported.", "'default_icon' must be an object, with explicit sizes."]
48 ?
YesSVG icons are not supported.
14SVG icons are not supported. Grayscale images will be treated as template icons and processed with the system accent color and system appearance.
? ? No ?
15SVG icons are not supported. Grayscale images will be treated as template icons and processed with the system accent color and system appearance.
?
default_popup Yes 14 48 ? Yes 14 ? ? 57 ? 15 ?
default_title Yes 14 48 ? Yes 14 ? ?
55Browser actions are presented as menu items, and the title is the menu item's label.
? 15 ?
theme_icons No No 56 ? No No ? ? No ? No ?
Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
Browser_styles 88 88 109 ? 74 15.4 ? ? 109 ? 15.4 ?
browser_style 88 88 109 ? 74 No ? ? No ? No ?
default_area 88 88 109 ? 74 No ? ? No ? No ?
default_icon
88SVG icons are not supported.
88["SVG icons are not supported.", "'default_icon' must be an object, with explicit sizes."]
109 ?
74SVG icons are not supported.
15.4SVG icons are not supported. Grayscale images will be treated as template icons and processed with the system accent color and system appearance.
? ? No ?
15.4SVG icons are not supported. Grayscale images will be treated as template icons and processed with the system accent color and system appearance.
?
default_popup 88 88 109 ? 74 15.4 ? ? 109 ? 15.4 ?
default_title 88 88 109 ? 74 15.4 ? ?
109Browser actions are presented as menu items, and the title is the menu item's label.
? 15.4 ?
theme_icons 88 88 109 ? 74 No ? ? No ? No ?

webextensions.manifest.action

BCD tables only load in the browser

webextensions.manifest.browser_action

BCD tables only load in the browser

webextensions.manifest.page_action

BCD tables only load in the browser

webextensions.manifest.sidebar_action

BCD tables only load in the browser

webextensions.manifest.options_ui

BCD tables only load in the browser

Firefox Panel Components

Note: This feature is non-standard and only works in Firefox.

The chrome://browser/content/extension.css stylesheet also contains the styles for the Firefox Panel Components.

The legacy Firefox Style Guide documents proper usage.

Element Example
Header 
<header class="panel-section panel-section-header">
  <div class="icon-section-header"><img src="image.svg"/></div>
  <div class="text-section-header">Header</div>
</header>
Footer 
<footer class="panel-section panel-section-footer">
  <button class="panel-section-footer-button">Cancel</button>
  <div class="panel-section-footer-separator"></div>
  <button class="panel-section-footer-button default">Confirm</button>
</footer>
Tabs 
<div class="panel-section panel-section-tabs">
  <button class="panel-section-tabs-button selected">Tab</button>
  <div class="panel-section-tabs-separator"></div>
  <button class="panel-section-tabs-button">Tab</button>
  <div class="panel-section-tabs-separator"></div>
  <button class="panel-section-tabs-button">Tab</button>
</div>
Form 
<div class="panel-section panel-section-formElements">
  <div class="panel-formElements-item">
    <label for="name01">Label:</label>
    <input type="text" value="Name" id="name01" />
  </div>
  <div class="panel-formElements-item">
    <label for="picker01">Label:</label>
    <select id="picker01">
      <option value="value1" selected="true">Dropdown</option>
      <option value="value2">List Item</option>
      <option value="value3">List Item</option>
    </select>
  </div>
  <div class="panel-formElements-item">
    <label for="placeholder01">Label:</label>
    <input type="text" placeholder="Placeholder" id="placeholder01" />
    <button name="expander" class="expander"></button>
  </div>
</div>
Menu 
<div class="panel-section panel-section-list">
  <div class="panel-list-item">
    <div class="icon"></div>
    <div class="text">List Item</div>
    <div class="text-shortcut">Ctrl-L</div>
  </div>
<div class="panel-list-item">
<div class="icon"></div>
<div class="text">List Item</div>
<div class="text-shortcut"></div>
</div>
<div class="panel-section-separator"></div>
<div class="panel-list-item disabled">
<div class="icon"></div>
<div class="text">Disabled List Item</div>
<div class="text-shortcut"></div>
</div>
<div class="panel-section-separator"></div>
<div class="panel-list-item">
<div class="icon"></div>
<div class="text">List Item</div>
<div class="text-shortcut"></div>
</div>
<div class="panel-list-item">
<div class="icon"></div>
<div class="text">List Item</div>
<div class="text-shortcut"></div>
</div>
</div>

Example

HTML

<header class="panel-section panel-section-header">
  <div class="icon-section-header"><!-- An image goes here. --></div>
  <div class="text-section-header">Header</div>
</header>

<div class="panel-section panel-section-list">
  <div class="panel-list-item">
    <div class="icon"></div>
    <div class="text">List Item</div>
    <div class="text-shortcut">Ctrl-L</div>
  </div>

  <div class="panel-list-item">
    <div class="icon"></div>
    <div class="text">List Item</div>
    <div class="text-shortcut"></div>
  </div>

  <div class="panel-section-separator"></div>

  <div class="panel-list-item disabled">
    <div class="icon"></div>
    <div class="text">Disabled List Item</div>
    <div class="text-shortcut"></div>
  </div>

  <div class="panel-section-separator"></div>

  <div class="panel-list-item">
    <div class="icon"></div>
    <div class="text">List Item</div>
    <div class="text-shortcut"></div>
  </div>

  <div class="panel-list-item">
    <div class="icon"></div>
    <div class="text">List Item</div>
    <div class="text-shortcut"></div>
  </div>
</div>

<footer class="panel-section panel-section-footer">
  <button class="panel-section-footer-button">Cancel</button>
  <div class="panel-section-footer-separator"></div>
  <button class="panel-section-footer-button default">Confirm</button>
</footer>

Result

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_styles