Addition of the `webextensions.api.tabGroups` documentation by rebloor · Pull Request #39370 · mdn/content

rebloor · 2025-05-02T18:50:44Z

Description

This PR adds the tabGroups API as documented in the API schema with additions for Chrome-only features as documented.

Related issues and pull requests

release note details documented in (PR TBD)
BCD details documented in (PR TBD)

github-actions · 2025-05-02T18:54:17Z

Preview URLs (19 pages)

External URLs (1)

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabGroups
Title: tabGroups

https://support.mozilla.org/en-US/kb/tab-groups (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-05-21 22:28:15)

Rob--W

Please also update tabs group(), ungroup(), Tab type, query articles to refer to the tabGroups article.

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/oncreated/index.md

Rob--W · 2025-05-06T10:27:17Z

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onmoved/index.md

+
+This event doesn't fire when a tab group is moved between windows; instead, the group is removed from one window and created in another (firing {{WebExtAPIRef("tabGroups.onRemoved")}} and {{WebExtAPIRef("tabGroups.onCreated")}}.


Suggested change

This event doesn't fire when a tab group is moved between windows; instead, the group is removed from one window and created in another (firing {{WebExtAPIRef("tabGroups.onRemoved")}} and {{WebExtAPIRef("tabGroups.onCreated")}}.

This text is copied from Chrome but not true in Firefox.

Relevant discussion in https://issues.chromium.org/issues/414993460#comment8 and the whole bug report in general.

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onmoved/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/tabgroup/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/update/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabs/onupdated/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/index.md

…index.md Co-authored-by: Rob Wu <rob@robwu.nl>

Co-authored-by: Rob Wu <rob@robwu.nl>

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Rob Wu <rob@robwu.nl>

Co-authored-by: Rob Wu <rob@robwu.nl>

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

github-actions · 2025-05-08T02:58:43Z

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onremoved/index.md

+
+Fires when a tab group is removed. This can occur when a user closes a tab group or a tab group is closed automatically because another change means it no longer contained any tabs.
+
+> [!NOTE] In Firefox, this event does not fire when a window is closed ([bug 1965007](https://bugzil.la/1965007)). As an alternative, use {{WebExtAPIRef("windows.onRemoved")}} to detect closed windows, and retrieve the remaining set of groups with {{WebExtAPIRef("tabGroups.query()")}}.


[markdownlint] _{reported by reviewdog 🐶}
search-replace Custom rule [bad-gfm-alert: Use the correct GFM syntax: > [!NOTE]] [Context: "column: 1 text:'> [!NOTE]'"]

Rob--W

Some clarifications, but mostly fixups (for missing periods in types and a few other smaller things).

I expect the PR to be ready to merge at the next review.

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/move/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/oncreated/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onmoved/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/query/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/update/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/move/index.md

Co-authored-by: Rob Wu <rob@robwu.nl>

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/color/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/tabgroup/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onmoved/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onremoved/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onmoved/index.md

dotproto · 2025-05-12T06:31:08Z

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/index.md

+
+This API enables extensions to modify and rearrange [tab groups](https://support.mozilla.org/en-US/kb/tab-groups).
+
+Tab groups persist across browser restarts, except for tab groups in private browsing windows. When a tab group is restored, its tab group ID may differ from its original value.


Should this line use groupId to be more explicit? If we have an established pattern in cases like this, let's use that. If not, I personally prefer using field names over descriptive names in situations like this.

Suggested change

Tab groups persist across browser restarts, except for tab groups in private browsing windows. When a tab group is restored, its tab group ID may differ from its original value.

Tab groups persist across browser restarts, except for tab groups in private browsing windows. When a tab group is restored, its `groupId` may differ from its original value.

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onmoved/index.md

Rob--W

Looks good to me. I'll let you and @dotproto complete the rest of the review (with the points that he added).

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onmoved/index.md

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/tabgroup/index.md

Co-authored-by: Simeon Vincent <svincent@gmail.com> Co-authored-by: Rob Wu <rob@robwu.nl>

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onupdated/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Rob--W · 2025-05-14T17:02:14Z

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onremoved/index.md

+
+> [!NOTE]
+> In Firefox, this event doesn't fire when a window closes ([bug 1965007](https://bugzil.la/1965007)). As an alternative, use {{WebExtAPIRef("windows.onRemoved")}} to detect closed windows, and retrieve the remaining set of groups with {{WebExtAPIRef("tabGroups.query()")}}.


Suggested change

> [!NOTE]

> In Firefox, this event doesn't fire when a window closes ([bug 1965007](https://bugzil.la/1965007)). As an alternative, use {{WebExtAPIRef("windows.onRemoved")}} to detect closed windows, and retrieve the remaining set of groups with {{WebExtAPIRef("tabGroups.query()")}}.

Suggested edit to remove the remark, because I plan to fix this issue and backport the patch so that the issue never reaches the 139 release.

Rob--W · 2025-05-14T17:04:43Z

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/move/index.md

+- `moveProperties`
+  - : An object containing details of the location to move the tab group to.
+    - `index`
+      - : `integer`. The position to move the group to. Use -1 to place the group at the end of the window.


Suggested change

- : `integer`. The position to move the group to. Use -1 to place the group at the end of the window.

- : `integer`. The position to move the group to. After moving, the first tab in the tab group will be at this index in the tab strip. Use -1 to place the group at the end of the window. Groups cannot be moved before a pinned tab or inside another group.

Clarification, because "the position" is apparently ambiguous. Here is a bug report in Firefox that we plan to address before the 139 release: https://bugzilla.mozilla.org/show_bug.cgi?id=1963825

The last sentence of this, I'm not sure if it should be in index or generally at the top of the documentation.

Regarding the note about pinned tabs, I'd like to keep this line here, but I think it may also make sense to mention movement limitations in subsection (or part) of the overview.

Rob--W · 2025-05-14T19:52:24Z

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onremoved/index.md

+
+    - `group`
+      - : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the removed tab group's state.
+


Could you also add removeInfo as additional information, with property isWindowClosing? You can re-use the content from https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/onRemoved , with just isWindowClosing (and no windowId), and "tab" replaced by "tab group".

This is part of the changes in https://bugzilla.mozilla.org/show_bug.cgi?id=1965007

Note: removeInfo is only supported in Firefox (planned for 139), Chrome does NOT have it.

@Rob--W done, I assume there was no need to document this as an extra object.

@Rob--W done, I assume there was no need to document this as an extra object.

You wrote "done", but the change is not reflected in the PR yet.

If by "not an extra object", you meant "not a separate article", then my answer is yes.

The BCD does need a new PR for removeInfo, because Chrome does not support it.

dotproto

Looks like this PR is very close. It looks like there are only a few items left

Two comment thread that have been marked "done" but haven't been pushed yet (thread 1, thread 2)
A note that can be removed (thread)

I took the liberty of resolving my example suggestion thread.

Once those threads are resolve I'm good to approve.

rebloor · 2025-05-21T02:58:07Z

@dotproto missing commit pushed. Please check.

Rob--W

Good to merge with these changes included. Please also update the BCD to mention removeInfo in tabGroups.onRenoved, it is not supported in Chrome, only in Firefox.

Rob--W · 2025-05-21T10:14:59Z

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onremoved/index.md

+
+> [!NOTE]
+> In Firefox, this event doesn't fire when a window closes ([bug 1965007](https://bugzil.la/1965007)). As an alternative, use {{WebExtAPIRef("windows.onRemoved")}} to detect closed windows, and retrieve the remaining set of groups with {{WebExtAPIRef("tabGroups.query()")}}.


Drop note, we fixed this issue before release: https://bugzilla.mozilla.org/show_bug.cgi?id=1965007#a729217_640478

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onremoved/index.md

Co-authored-by: Rob Wu <rob@robwu.nl>

Rob--W · 2025-05-23T11:04:07Z

This PR cannot be merged because @dotproto is marked as a blocking reviewer. He however wrote that the PR looks good with minor adjustments (#39370 (review)), which I confirm have since been applied.

rebloor · 2025-05-23T17:50:49Z

@Rob--W even when @dotproto has approved it still won't be possible for me to merge without "1 approving review by reviewers with write access." This appears to be a new requirement, and I followed up on Slack to get a list of appropriate reviewers.

Rob--W · 2025-05-23T18:09:56Z

@dotproto approved the other PR (in the BCD), not this one.

Addition of the webextensions.api.tabGroups documentation

47d05b8

rebloor requested a review from a team as a code owner May 2, 2025 18:50

rebloor requested review from willdurand and removed request for a team May 2, 2025 18:50

github-actions bot added Content:WebExt WebExtensions docs size/l [PR only] 501-1000 LoC changed labels May 2, 2025

rebloor marked this pull request as draft May 2, 2025 18:54

rebloor requested review from Rob--W and dotproto and removed request for willdurand May 2, 2025 18:54

rebloor self-assigned this May 2, 2025

rebloor added 3 commits May 3, 2025 07:05

Update tabs API with reference to tabGroups.TAB_GROUP_ID_NONE

e14dcfb

Merge branch 'main' into Add-tabGroups-API

a717a38

Additional documentation per Chrome

af5f98e

rebloor marked this pull request as ready for review May 5, 2025 04:13

Merge branch 'main' into Add-tabGroups-API

579d0e3

This was referenced May 6, 2025

Add webextensions.api.tabGroups API mdn/browser-compat-data#26724

Merged

tabGroups API release note #39430

Merged

Clarified onMove differences in Chrome

5c91eac

Rob--W requested changes May 7, 2025

View reviewed changes

rebloor and others added 9 commits May 8, 2025 14:49

Update files/en-us/mozilla/add-ons/webextensions/api/tabgroups/color/…

5796ebc

…index.md Co-authored-by: Rob Wu <rob@robwu.nl>

Update files/en-us/mozilla/add-ons/webextensions/api/tabgroups/index.md

7301671

Co-authored-by: Rob Wu <rob@robwu.nl>

Update files/en-us/mozilla/add-ons/webextensions/api/tabgroups/index.md

1d24f35

Co-authored-by: Rob Wu <rob@robwu.nl>

Apply suggestions from review

15513a5

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Rob Wu <rob@robwu.nl>

Apply suggestions from review

da46206

Co-authored-by: Rob Wu <rob@robwu.nl>

Apply suggestions from review

81fa00c

Co-authored-by: Rob Wu <rob@robwu.nl>

Apply suggestions from review

6e0ea9f

Co-authored-by: Rob Wu <rob@robwu.nl>

Apply suggestions from review

0542e29

Co-authored-by: Rob Wu <rob@robwu.nl>

Apply suggestions from linter

4ba4715

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

github-actions bot reviewed May 8, 2025

View reviewed changes

Further feedback changes

f6e8436

rebloor requested a review from Rob--W May 8, 2025 15:19

Rob--W requested changes May 11, 2025

View reviewed changes

Apply suggestions from review

1a7bc19

Co-authored-by: Rob Wu <rob@robwu.nl>

rebloor requested a review from Rob--W May 12, 2025 02:35

dotproto suggested changes May 12, 2025

View reviewed changes

dotproto reviewed May 12, 2025

View reviewed changes

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onmoved/index.md Show resolved Hide resolved

dotproto reviewed May 12, 2025

View reviewed changes

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onmoved/index.md Outdated Show resolved Hide resolved

Rob--W approved these changes May 12, 2025

View reviewed changes

Apply suggestions from review

c581e68

Co-authored-by: Simeon Vincent <svincent@gmail.com> Co-authored-by: Rob Wu <rob@robwu.nl>

rebloor requested a review from dotproto May 12, 2025 11:52

github-actions bot reviewed May 12, 2025

View reviewed changes

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onupdated/index.md Outdated Show resolved Hide resolved

files/en-us/mozilla/add-ons/webextensions/api/tabgroups/onupdated/index.md Outdated Show resolved Hide resolved

Linter feedback on review changes

8959d01

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Rob--W reviewed May 14, 2025

View reviewed changes

Feedback update updates

65222de

rebloor requested a review from Rob--W May 14, 2025 23:50

dotproto reviewed May 15, 2025

View reviewed changes

Rob--W approved these changes May 21, 2025

View reviewed changes

rebloor and others added 2 commits May 22, 2025 10:23

Review feedback

200a705

Co-authored-by: Rob Wu <rob@robwu.nl>

Remove note about resolved bug

ceef2b5

rebloor mentioned this pull request May 21, 2025

Bug-1965007 added removeInfo to tabGroups.onRemoved mdn/browser-compat-data#26872

Merged

dotproto approved these changes May 23, 2025

View reviewed changes

rebloor merged commit 3ffce2e into mdn:main May 23, 2025
8 checks passed

rebloor deleted the Add-tabGroups-API branch May 23, 2025 18:48


		This event doesn't fire when a tab group is moved between windows; instead, the group is removed from one window and created in another (firing {{WebExtAPIRef("tabGroups.onRemoved")}} and {{WebExtAPIRef("tabGroups.onCreated")}}.


		Fires when a tab group is removed. This can occur when a user closes a tab group or a tab group is closed automatically because another change means it no longer contained any tabs.

		> [!NOTE] In Firefox, this event does not fire when a window is closed ([bug 1965007](https://bugzil.la/1965007)). As an alternative, use {{WebExtAPIRef("windows.onRemoved")}} to detect closed windows, and retrieve the remaining set of groups with {{WebExtAPIRef("tabGroups.query()")}}.


		This API enables extensions to modify and rearrange [tab groups](https://support.mozilla.org/en-US/kb/tab-groups).

		Tab groups persist across browser restarts, except for tab groups in private browsing windows. When a tab group is restored, its tab group ID may differ from its original value.


		> [!NOTE]
		> In Firefox, this event doesn't fire when a window closes ([bug 1965007](https://bugzil.la/1965007)). As an alternative, use {{WebExtAPIRef("windows.onRemoved")}} to detect closed windows, and retrieve the remaining set of groups with {{WebExtAPIRef("tabGroups.query()")}}.

	- : `integer`. The position to move the group to. Use -1 to place the group at the end of the window.
	- : `integer`. The position to move the group to. After moving, the first tab in the tab group will be at this index in the tab strip. Use -1 to place the group at the end of the window. Groups cannot be moved before a pinned tab or inside another group.


		- `group`
		- : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the removed tab group's state.

Conversation

rebloor commented May 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related issues and pull requests

Uh oh!

github-actions bot commented May 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Rob--W left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot May 8, 2025

Choose a reason for hiding this comment

Uh oh!

Rob--W left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Rob--W left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dotproto left a comment

Choose a reason for hiding this comment

Uh oh!

rebloor commented May 21, 2025

Uh oh!

Rob--W left a comment

rebloor commented May 2, 2025 •

edited

Loading

github-actions bot commented May 2, 2025 •

edited

Loading