offscreen.md

offscreen

Documentation: Chrome Offscreen API

A promise-based wrapper for the Chrome offscreen API to create and manage offscreen documents.

Methods

• isAvailableOffscreen()
• createOffscreen(parameters)
• closeOffscreen()
• hasOffscreen()
• getOffscreenContext()
• getOffscreenUrl()
• getOffscreenPath()
• hasOffscreenUrl(url)
• hasOffscreenPath(path)

---

isAvailableOffscreen

isAvailableOffscreen(): boolean

Returns true when the offscreen namespace is present on the API selected by browser() in the current context. Returns false if the namespace or WebExtension environment is absent, or if accessing it throws. The check is synchronous, does not log, and reads the current API on every call without caching. It checks namespace presence only; it does not guarantee individual methods, permissions, or a successful operation.

import {isAvailableOffscreen} from "@addon-core/browser";

if (isAvailableOffscreen()) {
    // The namespace is present; handle operation-specific failures when using it.
}

createOffscreen

createOffscreen(parameters: chrome.offscreen.CreateParameters): Promise<void>

Creates an offscreen document with the specified parameters.

closeOffscreen

closeOffscreen(): Promise<void>

Closes the existing offscreen document.

hasOffscreen

hasOffscreen(): Promise<boolean>

Directly proxies the native offscreen.hasDocument() method. Resolves to its boolean result and preserves native errors as Promise rejections; this method does not convert failures into false.

getOffscreenContext

getOffscreenContext(): Promise<chrome.runtime.ExtensionContext | undefined>

Returns the current offscreen document context, if one is open.

getOffscreenUrl

getOffscreenUrl(): Promise<string | undefined>

Returns the current offscreen document URL, if one is open.

getOffscreenPath

getOffscreenPath(): Promise<string | undefined>

Returns the current offscreen document path within the extension, if one is open. Query parameters and hash fragments are not included.

hasOffscreenUrl

hasOffscreenUrl(url: string): Promise<boolean>

Returns true when the current offscreen document matches the given URL. Returns false when no match can be confirmed, including missing APIs or failed context queries. Does not throw, reject, log, or cache. Use getOffscreenUrl() when query errors must remain observable.

hasOffscreenPath

hasOffscreenPath(path: string): Promise<boolean>

Returns true when the current offscreen document matches the given extension path. Query parameters and hash fragments are ignored. Returns false when no match can be confirmed, including API access, context lookup, and URL parsing failures. Does not throw, reject, log, or cache. Use getOffscreenPath() when query errors must remain observable.