Add `action.setBadgeStyle()`

[carlosjeurissen]

Introduction

Considering the preference for declarative declaration of theme data for smooth light / dark theme transitions as discussed in #869, having a way to specify both dark and light versions of the badge theme would be very welcome.

Before proceeding with a proposal doc, wanted to hear from the group what direction to head into.

With both proposal A and B, both the text color and background colors are set at the same time. Requesting to specify both of them at the same time can reduce potential contrast issues and visual glitches due to two API calls being required.

Proposal A - variant list

This API design would utilise a similar concept as we have been using for icon_variants. In which you pass a set of potential variations which include both the data to set as well as the required filter matches.

Example same for all themes

browser.action.setBadgeStyle([{
  textColor: '#000000',
  backgroundColor: '#ffffff',
}]);

Example different per colorScheme

browser.action.setBadgeStyle([{
  textColor: '#ffffff',
  backgroundColor: '#000000',
  colorSchemes: ['dark'],
}, {
  textColor: '#000000',
  backgroundColor: '#ffffff',
}]);

Proposal B - nested objects

Example same for all themes

browser.action.setBadgeStyle({
    textColor: '#ffffff',
    backgroundColor: '#000000',
  });

Example different per colorScheme

browser.action.setBadgeStyle({
  light: {
    textColor: '#ffffff',
    backgroundColor: '#000000',
  },
  dark: {
  textColor: '#000000',
  backgroundColor: '#ffffff',
},
});

Proposal C - setIcon approach with tabId and windowId support

browser.action.setBadgeStyle({
  textColor: '#000000',
  backgroundColor: '#ffffff',
  tabId: 200,
});

and separate variants per color scheme:

browser.action.setBadgeStyle({
  tabId: 200,
  variants: [{
    textColor: '#ffffff',
    backgroundColor: '#000000',
    colorSchemes: ['dark'],
  }, {
    textColor: '#000000',
    backgroundColor: '#ffffff',
  }]
});

Conclusion

These APIs would have the potential to replace the action.setBadgeBackgroundColor and action.setBadgeTextColor APIs.

Each proposal have different pros and cons in terms of flexibility, understandability and their future-proof aspect. So love to hear from the group what your thoughts are.

[xeenon]

While we don't support color changes for the badge today in Safari, I'm supportive of this proposal as it would be needed for us to consider allowing color changes. I prefer proposal A, as it is similar to icon_variants.

[carlosjeurissen]

@Rob--W can you clarify on your unified approach you briefly mentioned during 2025-10-09 meeting?

@oliverdunk love to hear chrome's perspective.

[Rob--W]

@Rob--W can you clarify on your unified approach you briefly mentioned during 2025-10-09 meeting?

Your request here is to have a way to set two existing properties of the extension (action) button at once, in a theme-aware way. I saw the possibility of not stopping at just two properties, but to proceed to a method that subsumes all properties at once.

For example:

// All properties optional and nullable.
browser.action.setOptions({
  title: "string",
  // Maybe icon to mirror setIcon, or:
  icon_variants: [], // see #229
  popup: "string/path.html",
  badgeText: "string",
  badgeBackgroundColor: ..., // TODO
  badgeTextColor: ..., // TODO
  enabled: true,
  // Maybe optional tabId or windowId property
});

icon_variants is described at #229

The badgeBackgroundColor and badgeTextColor properties are yet to be specified here; could be a plain string, an array of objects or an object (following the conventions of icon_variants).

The discussion on whether to have individual setters vs one batch-setter is comparable to discussions about unifying sidebar_action/sidepanel, where we converged towards the desire to have a single setter method, for various reasons. See e.g. #128 and the discussion at https://github.com/w3c/webextensions/blob/main/_minutes/2024-03-18-san-diego-meetup.md#inconsistencies where the conclusion is that the unified API should have a way to batch-set multiple properties at once. Here is an example of Chrome's sidePanel.setOptions that puts this to practice: https://developer.chrome.com/docs/extensions/reference/api/sidePanel#method-setOptions

[carlosjeurissen]

@Rob--W Thanks for elaborating! The point of joining seemingly unrelated properties badgeBackgroundColor and badgeTextColor together is not at random. One of the benefits being if you set one of them instead of both. For example, setting just a background color would reset the text color to browser default (some contrast color which works with the background color).

The other properties like title, popup, enabled. are not necessarily connected to each other. Unlike the setOptions in sidePanel (in which just path and enabled are connected). A sidePanel without a path does not make sense, yet an action button without a popup can make total sense.

You do make a good point on separate settings for per-tab and per-window. A potential alternative design would be:
Example same for same style for all themes:

browser.action.setBadgeStyle({
  textColor: '#000000',
  backgroundColor: '#ffffff',
  tabId: 200,
});

and separate variants per color scheme:

browser.action.setBadgeStyle({
  tabId: 200,
  variants: [{
    textColor: '#ffffff',
    backgroundColor: '#000000',
    colorSchemes: ['dark'],
  }, {
    textColor: '#000000',
    backgroundColor: '#ffffff',
  }]
});

This would make it align perfectly with action.setIcon(); another style-related method.

Following your logic, one could potentially consider action.setBadge(), joining textColor, backgroundColor, and text together. However question is what if you do not set one of the properties? Will it reset the others? How to set the separate styles for different color schemes?