Addition of the webextensions.api.tabGroups documentation

mdn · rebloor · May 23, 2025 · May 2, 2025 · May 2, 2025 · May 2, 2025
commit 47d05b8ad6c4691cfd74521d0298437e60ae83ce
@@ -0,0 +1,33 @@
+---
+title: tabGroups.Color
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/Color
+page-type: webextension-api-type
+browser-compat: webextensions.api.tabGroups.Color
+---
+
+{{AddonSidebar}}
+
+The color of a tab group.
+
+## Type
+
+Values of this type are a {{jsxref("string")}} and can take these values:
+
+- blue
+- cyan
+- grey
+- green
+- orange
+- pink
+- purple
+- red
+- yello
+
+> [!NOTE]
+> The British English spelling of grey is used to maintain compatibility with Chrome.
+
+{{WebExtExamples("h2")}}
+
+## Browser compatibility
+
+{{Compat}}
@@ -0,0 +1,33 @@
+---
+title: tabGroups.get
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/get
+page-type: webextension-api-function
+browser-compat: webextensions.api.tabGroups.get
+---
+
+{{AddonSidebar}}
+
+Returns details about a tab group.
+
+## Syntax
+
+```js-nolint
+let tabGroupDetails = await browser.tabGroups.get(
+    groupId                // integer
+);
+```
+
+### Parameters
+
+- `groupId`
+  - : `integer` The ID of the tab group to return details for.
+
+### Return value
+
+A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with a {{WebExtAPIRef("tabGroups.TabGroup")}} object. If the request fails, the promise is rejected with an error message.
+
+{{WebExtExamples("h2")}}
+
+## Browser compatibility
+
+{{Compat}}
@@ -0,0 +1,54 @@
+---
+title: tabGroups
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups
+page-type: webextension-api
+browser-compat: webextensions.api.tabGroups
+---
+
+{{AddonSidebar}}
+
+This API enables extensions to modify and rearrange tab groups.
+
+## Permissions
+
+To use this API, an extension must request the `"tabGroups"` [optional permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) in its [`manifest.json`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json) file. The `"tabGroups"` permission is not shown to users in permission prompts.
+
+## Types
+
+- {{WebExtAPIRef("tabGroups.Color")}}
+  - : The color of a tab group.
+- {{WebExtAPIRef("tabGroups.TabGroup")}}
+  - : The state of a tab group.
+
+## Properties
+
+- {{WebExtAPIRef("tabGroups.TAB_GROUP_ID_NONE")}}
+  - : The tab group ID value returned when a tab isn't in a tab group.
+
+## Functions
+
+- {{WebExtAPIRef("tabGroups.get()")}}
+  - : Returns details about a tab group.
+- {{WebExtAPIRef("tabGroups.move()")}}
+  - : Moves a tab group within or to another window.
+- {{WebExtAPIRef("tabGroups.query()")}}
+  - : Returns all grups or finds tab groups with certain properties.
+- {{WebExtAPIRef("tabGroups.update()")}}
+  - : Modifies the state of a tab group.
+
+## Events
+
+- {{WebExtAPIRef("tabGroups.onCreated")}}
+  - : Fires when a tab group is created.
+- {{WebExtAPIRef("tabGroups.onMoved")}}
+  - : Fires when a tab group is moved, within a window or to another window.
+- {{WebExtAPIRef("tabGroups.onRemoved")}}
+  - : Fires when a tab group is removed.
+- {{WebExtAPIRef("tabGroups.onUpdated")}}
+  - : Fires when a tab group is updated.
+
+{{WebExtExamples("h2")}}
+
+## Browser compatibility
+
+{{Compat}}
@@ -0,0 +1,42 @@
+---
+title: tabGroups.move
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/move
+page-type: webextension-api-function
+browser-compat: webextensions.api.tabGroups.move
+---
+
+{{AddonSidebar}}
+
+Moves a tab group within or to another window.
+
+## Syntax
+
+```js-nolint
+let movedTabGroup = await browser.tabGroups.move(
+    groupId,                // integer
+    moveProperties          // object
+);
+```
+
+### Parameters
+
+- `groupId`
+
+  - : `integer` The ID of the tab group to move.
+
+- `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.
+    - `windowId` {{optional_inline}}
+      - : `integer` The window to move the group to. Defaults to the window the group is in. Groups can only be moved to and from windows with {{WebExtAPIRef("windows.WindowType")}} type `"normal"`.
+
+### Return value
+
+A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with a {{WebExtAPIRef("tabGroups.TabGroup")}} object. If the request fails, the promise is rejected with an error message.
+
+{{WebExtExamples("h2")}}
+
+## Browser compatibility
+
+{{Compat}}
@@ -0,0 +1,56 @@
+---
+title: tabGroups.onCreated
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onCreated
+page-type: webextension-api-event
+browser-compat: webextensions.api.tabGroups.onCreated
+---
+
+{{AddonSidebar}}
+
+Fires when a tab group is created.
+
+## Syntax
+
+```js-nolint
+browser.tabGroups.onCreated.addListener(listener)
+browser.tabGroups.onCreated.removeListener(listener)
+browser.tabGroups.onCreated.hasListener(listener)
+```
+
+Events have three functions:
+
+- `addListener(listener)`
+  - : Adds a listener to this event.
+- `removeListener(listener)`
+  - : Stops listening to this event. The `listener` argument is the listener to remove.
+- `hasListener(listener)`
+  - : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.
+
+## addListener syntax
+
+### Parameters
+
+- `listener`
+
+  - : The function called when this event occurs. The function is passed this argument:
+
+    - `group`
+      - : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the created tab group's state.
+
+## Examples
+
+Listen for and log tab group creation:
+
+```js
+function tabGroupCreated(group) {
+  console.log(`Tab with ID ${group.id} was created.`);
+}
+
+browser.tabGroups.onCreated.addListener(tabGroupCreated);
+```
+
+{{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}
@@ -0,0 +1,56 @@
+---
+title: tabGroups.onMoved
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onMoved
+page-type: webextension-api-event
+browser-compat: webextensions.api.tabGroups.onMoved
+---
+
+{{AddonSidebar}}
+
+Fires when a tab group is moved, within a window or to another window.
+
+## Syntax
+
+```js-nolint
+browser.tabGroups.onMoved.addListener(listener)
+browser.tabGroups.onMoved.removeListener(listener)
+browser.tabGroups.onMoved.hasListener(listener)
+```
+
+Events have three functions:
+
+- `addListener(listener)`
+  - : Adds a listener to this event.
+- `removeListener(listener)`
+  - : Stops listening to this event. The `listener` argument is the listener to remove.
+- `hasListener(listener)`
+  - : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.
+
+## addListener syntax
+
+### Parameters
+
+- `listener`
+
+  - : The function called when this event occurs. The function is passed this argument:
+
+    - `group`
+      - : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the moved tab group's state.
+
+## Examples
+
+Listen for and log tab group movement:
+
+```js
+function tabGroupMoved(group) {
+  console.log(`Tab with ID ${group.id} was moved to window ${group.windotId}.`);
+}
+
+browser.tabGroups.onMoved.addListener(tabGroupMoved);
+```
+
+{{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}
@@ -0,0 +1,56 @@
+---
+title: tabGroups.onRemoved
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onRemoved
+page-type: webextension-api-event
+browser-compat: webextensions.api.tabGroups.onRemoved
+---
+
+{{AddonSidebar}}
+
+Fires when a tab group is removed.
+
+## Syntax
+
+```js-nolint
+browser.tabGroups.onRemoved.addListener(listener)
+browser.tabGroups.onRemoved.removeListener(listener)
+browser.tabGroups.onRemoved.hasListener(listener)
+```
+
+Events have three functions:
+
+- `addListener(listener)`
+  - : Adds a listener to this event.
+- `removeListener(listener)`
+  - : Stops listening to this event. The `listener` argument is the listener to remove.
+- `hasListener(listener)`
+  - : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.
+
+## addListener syntax
+
+### Parameters
+
+- `listener`
+
+  - : The function called when this event occurs. The function is passed this argument:
+
+    - `group`
+      - : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the removed tab group's state.
+
+## Examples
+
+Listen for and log tab group removals:
+
+```js
+function tabGroupRemoved(group) {
+  console.log(`Tab with ID ${group.id} was removed.`);
+}
+
+browser.tabGroups.onRemoved.addListener(tabGroupRemoved);
+```
+
+{{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}
@@ -0,0 +1,56 @@
+---
+title: tabGroups.onUpdated
+slug: Mozilla/Add-ons/WebExtensions/API/tabGroups/onUpdated
+page-type: webextension-api-event
+browser-compat: webextensions.api.tabGroups.onUpdated
+---
+
+{{AddonSidebar}}
+
+Fires when a tab group is updated.
+
+## Syntax
+
+```js-nolint
+browser.tabGroups.onUpdated.addListener(listener)
+browser.tabGroups.onUpdated.removeListener(listener)
+browser.tabGroups.onUpdated.hasListener(listener)
+```
+
+Events have three functions:
+
+- `addListener(listener)`
+  - : Adds a listener to this event.
+- `removeListener(listener)`
+  - : Stops listening to this event. The `listener` argument is the listener to remove.
+- `hasListener(listener)`
+  - : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.
+
+## addListener syntax
+
+### Parameters
+
+- `listener`
+
+  - : The function called when this event occurs. The function is passed this argument:
+
+    - `group`
+      - : {{WebExtAPIRef("tabGroups.TabGroup")}}. Details of the updated tab group's state.
+
+## Examples
+
+Listen for and log tab group updates:
+
+```js
+function tabGroupUpdated(group) {
+  console.log(`Tab with ID ${group.id} was updated.`);
-  console.log(`Tab with ID ${group.id} was updated.`);
+  console.log(`Tab group with ID ${group.id} was updated.`, group);
-  console.log(`Tab with ID ${group.id} was updated.`);
+  console.log(`Tab group with ID ${group.id} was updated.`, group);
+}
+
+browser.tabGroups.onUpdated.addListener(tabGroupUpdated);
+```
+
+{{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}