Welcome What's new in Chrome extensions API reference Samples
Welcome What's new in Chrome extensions API reference Samples

chrome.offscreen

  • Description

    Use the offscreen API to create and manage offscreen documents.

  • Permissions
    offscreen
  • Availability
    Chrome 109+ MV3+

Manifest

You must declare the "offscreen" permission in the [extension manifest][1] to use the Offscreen API. For example:

{
"name": "My extension",
...
"permissions": [
"offscreen"
],
...
}

Pages loaded as offscreen documents are handled differently from other types of extension pages. The extension's permissions carry over to offscreen documents, but extension API access is heavily limited. Currently, an offscreen document can only use the chrome.runtime APIs to send and receive messages; all other extension APIs are not exposed. Other notable differences between offscreen documents and normal pages are as follows:

  • An offscreen document's URL must be a static HTML file bundled with the extension.
  • Offscreen documents cannot be focused.
  • Offscreen documents cannot have their opener property set using the chrome.windows API method windows.setSelfAsOpener().
  • An extension can only have one offscreen document open at a time. If the extension is running in split mode with an active incognito profile, both the normal and incognito profiles can each have one offscreen document.

Reasons

Reasons, listed below, are set upon document creation to determine the document's lifespan. Currently, the AUDIO_PLAYBACK reason has specialized lifetime enforcement (CreateAudioLifetimeEnforcer). All others use generic idle detection (CreateEmptyEnforcer).

Examples

The following methods create and close an offscreen document. Only a single Document can be open at a time.

chrome.offscreen.createDocument({
url: chrome.runtime.getURL('off_screen.html'),
reasons: ['CLIPBOARD'],
justification: 'reason for needing the document',
});

chrome.offscreen.closeDocument()

Summary

Types

CreateParameters

Properties

  • justification

    string

    A developer-provided string that explains, in more detail, the need for the background context. The user agent _may_ use this in display to the user.

  • reasons

    The reason(s) the extension is creating the offscreen document.

  • url

    string

    The (relative) URL to load in the document.

Reason

Type

"TESTING"

,

"AUDIO_PLAYBACK"

,

"IFRAME_SCRIPTING"

,

"DOM_SCRAPING"

,

"BLOBS"

,

"DOM_PARSER"

,

"USER_MEDIA"

,

"DISPLAY_MEDIA"

,

"WEB_RTC"

,
or

"CLIPBOARD"

Methods

closeDocument

chrome.offscreen.closeDocument(
  callback?: function,
)
Promise

Closes the currently-open offscreen document for the extension.

Parameters

  • callback

    function optional

    The callback parameter looks like: () => void

Returns

  • Promise<void>

    In Manifest V3 and later, return a Promise by omitting the callback argument. The type inside the Promise is the same as the 1st argument to callback.

createDocument

chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)
Promise

Creates a new offscreen document for the extension.

Parameters

  • The parameters describing the offscreen document to create.

  • callback

    function optional

    The callback parameter looks like: () => void

Returns

  • Promise<void>

    In Manifest V3 and later, return a Promise by omitting the callback argument. The type inside the Promise is the same as the 1st argument to callback.

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.