Browser styles

Your extension can include user interface elements - browser and page action popups, sidebars, and options pages - that are specified by:

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

You can style these elements to match the browser's style. The manifest.json keys include an optional property to help with this: browser_style. If this is included and set to true, your document gets one or more extra stylesheets that help make it look consistent with the browser's UI and with other extensions that use the browser_style property.

Note: Support for browser_style in Manifest V3 is deprecated. Starting from Firefox 115, the default value of options_ui.browser_style and sidebar_action.browser_style changes from true to false. In Firefox 118, "browser_style": true will no longer be supported in Manifest V3 extensions. If your Manifest V3 extension depends on the "browser_style": true styles, follow the Manifest V3 migration guide for browser_style. See (Firefox bug 1827910) for more information. If you want to apply the Firefox style to your extension, see the Firefox Style Guide.

When considering whether to use browser_style: true, test your extension with various themes (built-in or from AMO) to ensure 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 causes a problem, include browser_style:false instead.

Note: Google Chrome and Opera use chrome_style instead of browser_style in Manifest V2. So for cross-browser extensions you need to add both keys. chrome_style is not available in Manifest V3.

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>
html
<button class="browser-style">Click me</button>

<select>

html
<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>
html
<textarea class="browser-style">Write here</textarea>
Parent of an <input>
html
<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>

Manifest V3 migration

As browser_style is a deprecated in Manifest V3 you may want to remove support when you migrate your Manifest V2 extensions. Using options_ui, as an example, you would you take these steps to remove support for browser_style:

  • Set options_ui/browser_style to false.
  • Does the appearance of your extensions UI change?
    • If the appearance doesn't change, remove the key.
    • If the appearance changes, experiment to determine what dependency exist and add the relevant properties in the extension's stylesheet. The styles are most likely to cause layout changes are box-sizing:, border-box, and display: flex. If you cannot identify the dependencies, include the content of extension.css with the extension and delete all parts that aren't relevant, usually the body and body * blocks as most extensions don't use the browser-style class.

Firefox panel components (legacy)

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

The chrome://browser/content/extension.css stylesheet also contains the styles for the legacy Firefox panel components (navigation components).

The legacy Firefox Style Guide documents proper usage.

Element Example
Header
html
<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
html
<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
html
<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
html
<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
html
<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

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

Browser compatibility

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