chrome.offscreen

# Manifest

You must declare the "offscreen" permission in the extension manifest 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.

# Example

Use chrome.offscreen.createDocument() and chrome.offscreen.closeDocument() for creating and closing 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()

The following example shows how to check for existing offscreen documents. The hasOffscreenDocument() function uses clients.matchAll() to find existing offscreen documents. Please note: the function assumes that your extension uses a single offscreen document.

async function hasOffscreenDocument(path) {
  // Check all windows controlled by the service worker to see if one 
  // of them is the offscreen document with the given path
  const offscreenUrl = chrome.runtime.getURL(path);
  const matchedClients = await clients.matchAll();
  for (const client of matchedClients) {
    if (client.url === offscreenUrl) {
      return true;
    }
  }
  return false;
}

Before trying to create a new offscreen document, call hasOffscreenDocument() to make sure that there is no existing offscreen document, as demonstrated in the following example.

chrome.action.onClicked.addListener(async () => {
  const offscreenDocumentPath = 'off_screen.html'
  // create offscreen document if it's not open already
  if (!(await hasOffscreenDocument(offscreenDocumentPath))) {
    await chrome.offscreen.createDocument({
      url: chrome.runtime.getURL(offscreenDocumentPath),
      reasons: ['CLIPBOARD'],
      justification: 'reason for needing the document',
    });
  }
  // Send message to offscreen document
  chrome.runtime.sendMessage({
    type: '...',
    target: 'offscreen',
    data: '...'
  });
});

For complete examples, see the offscreen-clipboard and offscreen-dom demos on GitHub.