web-navigation.md

webNavigation

Documentation: Chrome Web Navigation API

A promise-based wrapper for the Chrome webNavigation API, providing methods to retrieve frame information and listen to navigation events.

Methods

• isAvailableWebNavigation()
• getAllFrames(tabId)
• getFrame(details)

Events

• onWebNavigationBeforeNavigate(callback, filters?)
• onWebNavigationCommitted(callback, filters?)
• onWebNavigationCompleted(callback, filters?)
• onWebNavigationCreatedNavigationTarget(callback, filters?)
• onWebNavigationDOMContentLoaded(callback, filters?)
• onWebNavigationErrorOccurred(callback, filters?)
• onWebNavigationHistoryStateUpdated(callback, filters?)
• onWebNavigationReferenceFragmentUpdated(callback, filters?)
• onWebNavigationTabReplaced(callback)

---

isAvailableWebNavigation

isAvailableWebNavigation(method?: ApiMethodName<typeof chrome.webNavigation>): boolean

The optional method is a native function name, for example isAvailableWebNavigation("getFrame"). Import the public ApiMethodName type from @addon-core/browser for your own typed helpers. This checks callable presence without invoking the method; permissions and argument support still require handling.

Returns true when the webNavigation 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. Without an argument, it checks namespace presence only. Pass a native method name to also check that it is callable. Neither form verifies permissions, argument support, or a successful operation. See method availability.

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

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

getAllFrames

getAllFrames(tabId: number): Promise<chrome.webNavigation.GetAllFrameResultDetails[]>

Retrieves information about all frames in the specified tab.

getFrame

getFrame(details: chrome.webNavigation.GetFrameDetails): Promise<chrome.webNavigation.GetFrameResultDetails | null>

Retrieves information about a specific frame. Rejects if no matching frame is found.

onWebNavigationBeforeNavigate

onWebNavigationBeforeNavigate(
  callback: (details: chrome.webNavigation.WebNavigationParentedCallbackDetails) => void,
  filters?: chrome.webNavigation.WebNavigationEventFilter
): () => void

Adds a listener that is called before a navigation occurs.

onWebNavigationCommitted

onWebNavigationCommitted(
  callback: (details: chrome.webNavigation.WebNavigationTransitionCallbackDetails) => void,
  filters?: chrome.webNavigation.WebNavigationEventFilter
): () => void

Adds a listener that is called when a navigation is committed.

onWebNavigationCompleted

onWebNavigationCompleted(
  callback: (details: chrome.webNavigation.WebNavigationFramedCallbackDetails) => void,
  filters?: chrome.webNavigation.WebNavigationEventFilter
): () => void

Adds a listener that is called when a document, including its resources, is completely loaded.

onWebNavigationCreatedNavigationTarget

onWebNavigationCreatedNavigationTarget(
  callback: (details: chrome.webNavigation.WebNavigationSourceCallbackDetails) => void,
  filters?: chrome.webNavigation.WebNavigationEventFilter
): () => void

Adds a listener that is called when a new window or tab is created to host a navigation.

onWebNavigationDOMContentLoaded

onWebNavigationDOMContentLoaded(
  callback: (details: chrome.webNavigation.WebNavigationFramedCallbackDetails) => void,
  filters?: chrome.webNavigation.WebNavigationEventFilter
): () => void

Adds a listener that is called when the page's DOM is fully constructed.

onWebNavigationErrorOccurred

onWebNavigationErrorOccurred(
  callback: (details: chrome.webNavigation.WebNavigationFramedErrorCallbackDetails) => void,
  filters?: chrome.webNavigation.WebNavigationEventFilter
): () => void

Adds a listener that is called when an error occurs and a navigation is aborted.

onWebNavigationHistoryStateUpdated

onWebNavigationHistoryStateUpdated(
  callback: (details: chrome.webNavigation.WebNavigationTransitionCallbackDetails) => void,
  filters?: chrome.webNavigation.WebNavigationEventFilter
): () => void

Adds a listener that is called when a frame's history is updated to a new URL.

onWebNavigationReferenceFragmentUpdated

onWebNavigationReferenceFragmentUpdated(
  callback: (details: chrome.webNavigation.WebNavigationTransitionCallbackDetails) => void,
  filters?: chrome.webNavigation.WebNavigationEventFilter
): () => void

Adds a listener that is called when the reference fragment of a frame is updated.

onWebNavigationTabReplaced

onWebNavigationTabReplaced(
  callback: (details: chrome.webNavigation.WebNavigationReplacementCallbackDetails) => void
): () => void

Adds a listener that is called when a tab is replaced by another tab.