Work with contextual identities: list, create, remove, and update contextual identities.

"Contextual identities", also known as "containers", are a browser feature which addresses the idea that users assume multiple identities when browsing the web, and wish to maintain some separation between these identities. For example, a user might consider their "work identity" separate from their "personal identity", and not want to share cookies between these two contexts.

With the contextual identities feature, each contextual identity has a name, a color, and an icon. New tabs can be assigned to an identity, and the name, icon, and color will appear in the address bar. Internally, each identity gets its own cookie store which is not shared with other tabs.

Contextual identities are an experimental feature in Firefox and are only enabled by default in Firefox Nightly. To enable them in other versions of Firefox, set the privacy.userContext.enabled preference to true. Note that although contextual identities are available in Firefox for Android, there's no UI to work with them in this version of the browser.

Before Firefox 57, the contextualIdentities API is only available if the contextual identities feature is itself enabled. If an extension tried to use the contextualIdentities API without the feature being enabled, then method calls would resolve their promises with false.

From Firefox 57 onwards, if an extension that uses the contextualIdentities API is installed, then the contextual identities feature will be enabled automatically. Note though that it's still possible for the user to disable the feature using the "privacy.userContext.enabled" preference. If this happens, then contextualIdentities method calls will reject their promises with an error message.

For more information about contextual identities in Firefox, see this guide.

Contextual identities are not currently supported in any other browsers.

To use this API you need to include the "contextualIdentities" permission in your manifest.json file.

Types

contextualIdentities.ContextualIdentity
Contains information about a contextual identity.

Functions

contextualIdentities.create()
Creates a new contextual identity.
contextualIdentities.get()
Retrieves a single contextual identity, given its cookie store ID.
contextualIdentities.query()
Retrieves all contextual identities, or all contextual identities with a particular name.
contextualIdentities.update()
Updates properties of an existing contextual identity.
contextualIdentities.remove()
Deletes a contextual identity.

Events

contextualIdentities.onCreated
Fired when a contextual identity is created.
contextualIdentities.onRemoved
Fired when a contextual identity is removed.
contextualIdentities.onUpdated
Fired when one or more properties of a contextual identity is updated.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
createChrome No support NoEdge No support NoFirefox Full support 53
Notes
Full support 53
Notes
Notes Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.
Opera No support NoFirefox Android Full support 53
Notes
Full support 53
Notes
Notes Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.
getChrome No support NoEdge No support NoFirefox Full support 53
Notes
Full support 53
Notes
Notes Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.
Notes Before version 57, this method resolves its promise with null if the given identity was not found.
Opera No support NoFirefox Android Full support 53
Notes
Full support 53
Notes
Notes Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.
Notes Before version 57, this method resolves its promise with null if the given identity was not found.
onCreatedChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
onRemovedChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
onUpdatedChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
queryChrome No support NoEdge No support NoFirefox Full support 53
Notes
Full support 53
Notes
Notes Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.
Opera No support NoFirefox Android Full support 53
Notes
Full support 53
Notes
Notes Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.
removeChrome No support NoEdge No support NoFirefox Full support 53
Notes
Full support 53
Notes
Notes Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.
Notes Before version 57, this method resolves its promise with null if the given identity was not found.
Opera No support NoFirefox Android Full support 53
Notes
Full support 53
Notes
Notes Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.
Notes Before version 57, this method resolves its promise with null if the given identity was not found.
updateChrome No support NoEdge No support NoFirefox Full support 53
Notes
Full support 53
Notes
Notes Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.
Notes Before version 57, this method resolves its promise with null if the given identity was not found.
Opera No support NoFirefox Android Full support 53
Notes
Full support 53
Notes
Notes Before version 57, this method resolves its promise with false if the contextual identities feature is disabled.
Notes Before version 57, this method resolves its promise with null if the given identity was not found.

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

Example extensions

Document Tags and Contributors

Tags: 
Contributors to this page: hellosct1, wbamberg, royaldark
Last updated by: hellosct1,