Add `action.restorePopup()`

[carlosjeurissen]

background

Our 2025-09-25 meeting discussed some of the use-cases of runtime.getManifest().

One use case is restoring the action popup back to the manifest state. Some extensions temporarily want to disable the popup so they can listen for action.onClicked. To later restore the popup behaviour.

Firefox currently this by setting the popup to null. Since Safari 18, this also works in Safari.

browser.action.setPopup({
  popup: null
});

To deal with this in a generic way in Chrome, one would need to get the specified popup from the manifest with runtime.getManifest().

api design

A more semantic api would be action.restorePopup() which is also easy to feature detect and can potentially overrule the sidePanel behaviour.

interface Action {
  restorePopup(options?: { tabId?: number; windowId?: number }): Promise<void>;
}

If I am correct calling action.setPopup({popup: null}) in Safari would not throw in Safari below 18, which makes feature-detection tricky. Have not tested this. If it turns out Safari properly throws an error before Safari 18, we could potentially stick to setting popup: null as Chrome does throw currently when calling setPopup with null.

sidePanel behavior

Up for discussion is whether or not the restorePopup() should reset the openPanelOnActionClick sidePanel feature.

chrome.sidePanel.setPanelBehavior({
  openPanelOnActionClick: false
});

[hanguokai]

We discussed this use case in the past. It already works by setPopup({popup: ''}).

[carlosjeurissen]

@hanguokai to clarify, setPopup({popup: ''}) removes the popup. while setPopup({popup: null}) restores the popup to what is set in the manifest file. Neither of which is a very semantic way to execute these actions. And as mentioned in the main post, setPopup({popup: null}) is currently not supported in Chrome.

[hanguokai]

To restore popup, developers can call setPopup({popup: 'popup.html'}). Because it is a static value, developers know it when writing code. My discussion ends here. Thanks!

[carlosjeurissen]

@hanguokai the point is to do it in a generic way for generic libraries, which would otherwise rely on runtime.getManifest().

[carlosjeurissen]

Discussed during 2025-10-09 meeting. The other candidates under action would be:
action.restorePopup()
action.removePopup()
action.restoreIcon() (otherwise you would have to set path to null, which is awkward when also using iconVariants)
action.restoreBadgeStyle() (text and background colors)
action.restoreTitle()

@oliverdunk @Rob--W @xeenon love to hear your async thoughts.

[carlosjeurissen]

@xeenon you mentioned one would still need to rely on hacky behaviour. However at least for future versions one could simply check on action.restorePopup, only if that is not available, use some userAgent sniffing to check for support.

Still believe having more semantic separate methods for restorePopup() and removePopup() would allow to at some point not rely on magic values like null and an empty string. If you do not read the documentation, how does it make sense this code:

browser.action.setPopup({
  popup: "",
});

will remove the popup

while this:

browser.action.setPopup({
  popup: null,
});

will add the popup back?

[Rob--W]

Firefox already supports the ability to clear by passing the null value, as a pattern in the API. We don't strictly need new methods to clear overrides, at the surface.

One very subtle aspect is the question of what resetting/restoring should do. There are three levels where the properties of the action button can be specified:

• manifest key
• setXXX call with windowId
• setXXX call with tabId

tabId overrides windowId (if any), which overrides the manifest definition. When only a property is set for tabId XOR windowId, then setting it to null effectively resets the value to the manifest default. When both tabId and windowId are set, then resetting windowId does not have a visible effect (because tabId takes precedence), but resetting the tabId causes a fallback to the window-specific override.

After an individual property is updated, the state of the button for the visible tab is recomputed. A batch-reset API that allows the extension to signal the desire to reset multiple properties and/or multiple levels and/or multiple tabs/windows would allow for a far more efficient way of resetting action properties than what can be done today. This considerate also applies to the ability to bulk-set properties as suggested at #884 (comment)

In case you are curious about how Firefox's implementation looks like, its implementation is in JS using (prototypical) inheritance:

• definition of all three levels: https://searchfox.org/firefox-main/rev/b30a9b734819436853abf4eba6d768037514b3f6/toolkit/components/extensions/ExtensionActions.sys.mjs#40-50
• methods to look up one or all relevant properties for a tab: https://searchfox.org/firefox-main/rev/b30a9b734819436853abf4eba6d768037514b3f6/toolkit/components/extensions/ExtensionActions.sys.mjs#107-127
• When there are no tab-specific overrides, the fallback is to the window-specific overrides (and if there is none, the global one, via the lines above): https://searchfox.org/firefox-main/rev/b30a9b734819436853abf4eba6d768037514b3f6/browser/components/extensions/parent/ext-browserAction.js#51-57
• method to set or reset a property: https://searchfox.org/firefox-main/rev/b30a9b734819436853abf4eba6d768037514b3f6/toolkit/components/extensions/ExtensionActions.sys.mjs#74-97