tabs.create()
=============

Creates a new tab.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let creating = browser.tabs.create(
  createProperties   // object
)
```

### Parameters

`createProperties`

`object`. Properties to give the new tab. To learn more about these properties, see the `tabs.Tab` documentation.

`active` Optional

`boolean`. Whether the tab should become the active tab in the window. If `false`, it has no effect. Does not affect whether the window is focused (see `windows.update`). Defaults to `true`.

`cookieStoreId` Optional

`string`. Use this to create a tab whose cookie store ID is `cookieStoreId`. This option is only available if the extension has the `"cookies"` permission. See Work with contextual identities for more information.

`discarded` Optional

`boolean`. Whether the tab is created and made visible in the tab bar without any content loaded into memory, a state known as discarded. The tab's content is loaded when the tab is activated.

`index` Optional

`integer`. The position the tab should take in the window. The provided value will be clamped to between zero and the number of tabs in the window.

`muted` Optional

`boolean`. Whether the tab should be muted. Defaults to `false`.

`openerTabId` Optional

`integer`. The ID of the tab that opened this tab. If specified, the opener tab must be in the same window as the newly created tab.

`openInReaderMode` Optional

`boolean`. If `true`, open this tab in Reader Mode. Defaults to `false`.

`pinned` Optional

`boolean`. Whether the tab should be pinned. Defaults to `false`.

`selected` Optional

`boolean`. Whether the tab should become the selected tab in the window. Defaults to `true`.

**Warning:** This property is deprecated, and is not supported in Firefox. Use `active` instead.

`title` Optional

`string`. The title of the tab. Allowed only if the tab is created with `discarded` set to `true`.

`url` Optional

`string`. The URL to navigate the tab to initially. Defaults to the New Tab Page.

Fully-qualified URLs must include a scheme (for example, 'http://www.google.com' not 'www.google.com').

For security reasons, in Firefox, this may not be a privileged URL. So passing any of the following URLs will fail:

* chrome: URLs
* javascript: URLs
* data: URLs
* file: URLs (i.e., files on the filesystem. However, to use a file packaged inside the extension, see below)
* privileged about: URLs (for example, `about:config`, `about:addons`, `about:debugging`). Non-privileged URLs (e.g., `about:blank`) are allowed.
* The New Tab page (`about:newtab`) can be opened if no value for URL is provided.

To load a page that's packaged with your extension, specify an absolute URL starting at the extension's manifest.json file. For example: '/path/to/my-page.html'. If you omit the leading '/', the URL is treated as a relative URL, and different browsers may construct different absolute URLs.

`windowId` Optional

`integer`. The window to create the new tab in. Defaults to the current window.


### Return value

A `Promise` that will be fulfilled with a `tabs.Tab` object containing details about the created tab. If the tab could not be created (for example, because `url` used a privileged scheme) the promise will be rejected with an error message.

The promise returned by `browser.tabs.create()` resolves as soon as the tab has been created. The tab may still be loading. To detect when the tab has finished loading, listen to the `tabs.onUpdated` or the `webNavigation.onCompleted` event before calling `tabs.create`.

Examples
--------

Open "https://example.org" in a new tab:


```js
function onCreated(tab) {
  console.log(`Created new tab: ${tab.id}`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

browser.browserAction.onClicked.addListener(() => {
  let creating = browser.tabs.create({
    url: "https://example.org",
  });
  creating.then(onCreated, onError);
});
```

### Example extensions

* commands
* contextual-identities
* find-across-tabs
* firefox-code-search
* open-my-page-button
* permissions
* store-collected-images
* tabs-tabs-tabs
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.