Skip to content

Add a proposal for a unified Sidebar API - #1206

Open
kiaraarose wants to merge 1 commit into
w3c:mainfrom
kiaraarose:sidebar-proposal
Open

kiaraarose wants to merge 1 commit into
w3c:mainfrom
kiaraarose:sidebar-proposal

Conversation

@kiaraarose

@kiaraarose kiaraarose commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Adds a proposal for a unified sidebar namespace and sidebar manifest key, unifying chrome.sidePanel and browser.sidebarAction. Sponsoring browser: Safari.

Related TPAC discussions

Related issues

This proposal takes the implementations of sidePanel (in Chrome and Safari) and sidebar_action
(Firefox and Safari) to work towards a unified API that can be implemented across all browser vendors.

Note: the Safari implementation is behind a feature flag in WebKit and has not shipped.
Comment thread proposals/sidebar.md
Comment on lines +260 to +273
A window has an *open state* for the extension. `open()`, `toggle()` and the
user opening the sidebar turn it on, and `close()`, `toggle()`, the user closing
the sidebar and closing the window turn it off. While it is on, the window shows
one sidebar pane for the extension, and the pane shows the panel that applies to
the window's **selected tab**: the tab's own panel if it has a tab-level panel,
otherwise the window panel, as long as the effective options are usable.

The pane stays open when the user switches tabs, and follows the selected tab.
When the user selects another tab, the pane shows the panel that applies to that
tab, and does not reload if that is the panel it was already showing. Whenever
no panel applies to the selected tab because the options are not usable, the
pane hides and the open state stays on, so the pane returns when a panel applies
again. A `close()`, or the user closing the sidebar in between, turns the open
state off, and the pane does not return. When the user opens the sidebar of an

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The open state belongs to the window, which is simple, but it behaves oddly when an extension has both a tab-level panel and a window panel. If the user opens tab A's own panel and then selects tab C, the pane shows the window panel on C even though the user never opened it. Closing from any tab turns the state off for all of them. The Alternatives section notes that Chrome keeps the state per panel. Is the window-wide behavior intended for the mixed case, or should the state be tracked separately for tab-level panels and the window panel?

The state also stays on while the pane is hidden, so any later setOptions that makes a panel usable brings the pane back, however long ago the user opened it and without a gesture. Abuse Mitigations says only a gesture opens UI. I'd either limit the return, for example to selecting a tab, or say here why it is acceptable.

Comment thread proposals/sidebar.md
Comment on lines +362 to +370
`onClosed` fires when the window stops showing a panel for which `onOpened`
fired:

* the pane is closed;
* another panel replaces it, including the pane swapping to another panel of the
extension on a tab switch (the pane stays open, but the panel it showed is
closed);
* the pane hides because no panel applies to the selected tab;
* its tab or window closes.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two gaps. The sidebar is a slot the browser shares between extensions, so the proposal should say whether another extension's panel, or the browser's own, replacing this one turns the open state off and fires onClosed. "Another panel replaces it" can be read either way.

The order on a tab switch between two panels also isn't stated. I'd have onClosed for the old panel fire before onOpened for the new one.

Comment thread proposals/sidebar.md
Comment on lines +335 to +336
* `setTitle` / `getTitle` set and read the title at the global, window, or tab
level. `title: null` removes the value at that level.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd fold the title into setOptions and getOptions, as the icon already is, so it can change together with path and enabled. That drops setTitle, getTitle and their details types, and the null and resolution rules stay the same. It also fits the direction we have been taking for other namespaces, where state is set through an options bag instead of one setter per property.

Comment thread proposals/sidebar.md
Comment on lines +345 to +351
* `setBehavior` / `getBehavior`: with `openPanelOnActionClick: true`, activating
the extension's action toggles the sidebar as `toggle()` does for the
`windowId` of the tab where the action was activated, instead of showing the
popup or dispatching the click event. The default is `false`. If the extension
has no `action` key, the setting applies to the browser's own button for the
extension, and is ignored in a browser that has none. The setting is persisted
across restarts, as it is in Chrome.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

openPanelOnActionClick changes how the action button behaves, and in the 2026-11-19 meeting (#1207) there was support for moving it to action, pending Chrome's input on #1126. I'd leave it out of this proposal and list it under Open Questions with a pointer to that issue.

Comment thread proposals/sidebar.md
atomically together with `path` and `enabled`; there is no separate `setIcon`.
`iconVariants` is as defined in this [proposal](dark_mode_extension_icons.md)
and in [PR 1134](https://github.com/w3c/webextensions/pull/1134). Unknown
properties in an icon group are ignored (issue 1119), and a relative path

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue 1119, issue 1122 and issue 1142 are plain text while the other issues are linked. The Failures paragraph is also long enough to split into two.

@justinlulejian

Copy link
Copy Markdown

Thanks for writing this up! Two questions from reading the proposal against what chrome.sidePanel does today. Each one has a short scenario and a suggested edit.

1. Does a bad argument throw or resolve?

Scenario

A typo: sidebar.setOptions({enabled: 'false'}).

  1. Failures: a call "that has a member of the wrong type, throws an error synchronously" (L213-L215).
  2. setOptions: an object "that sets no known member to a valid value or null, resolves and changes nothing" (L307-L309).

The call matches both. With "resolves", the panel stays enabled and the developer sees no error. Sentence 2 also implies that an unknown member ({enbaled: false}) is ignored. The Failures section does not mention unknown members.

Suggestion

For the method argument objects (SetOptionsDetails, TargetDetails, and the like), I suggest: "A known member of the wrong type throws. An unknown member throws." Then shorten the setOptions sentence to "An empty object resolves and changes nothing." The rule that unknown properties in an icon group are ignored (L340-L341) stays as it is.

2. Is the legacy namespace exposed when the manifest has both keys?

Scenario

For a migration, a manifest lists side_panel, sidebar, and the sidePanel permission.

  1. New code calls browser.sidebar. An older module still calls browser.sidePanel.open({tabId}).
  2. The sidebar key overrides the side_panel and sidebar_action declarations, "which are ignored" (L390-L392). The text does not say if the legacy namespace still exists for this extension.

Suggestion

I suggest a general rule: "When the sidebar key is present, the browser does not expose the sidePanel namespace that the key overrides (sidePanel, sidebarAction) to that extension." Without it, two namespaces with different rules drive one panel in a migration manifest.

@carlosjeurissen carlosjeurissen added the topic: sidebar Discussions related to the sidebarAction and sidePanel APIs label Nov 20, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

topic: sidebar Discussions related to the sidebarAction and sidePanel APIs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants