webNavigation Permission
2 min readwebNavigation Permission
What It Grants
Access to the chrome.webNavigation API for monitoring page navigation lifecycle across all tabs and frames.
Manifest
{
"permissions": ["webNavigation"]
}
User Warning
None — this permission does not trigger a warning at install time.
API Access
When granted, you can use all chrome.webNavigation events:
onBeforeNavigate— before navigation startsonCommitted— navigation committed (headers received)onDOMContentLoaded— DOM readyonCompleted— page fully loadedonErrorOccurred— navigation failedonCreatedNavigationTarget— new tab opened by navigationonReferenceFragmentUpdated— hash/fragment changedonHistoryStateUpdated—pushState/replaceState(SPA navigation)onTabReplaced— tab replaced (prerender)getAllFrames(tabId)— list all frames in a tabgetFrame(tabId, frameId)— get specific frame info
URL Filtering
chrome.webNavigation.onCompleted.addListener(
(details) => { /* only matching URLs */ },
{ url: [{ hostSuffix: '.github.com' }, { urlPrefix: 'https://docs.google.com/' }] }
);
Key Properties
Each event provides:
tabId— which taburl— navigation URLframeId— 0 for main frame, >0 for subframesparentFrameId— parent frame IDtimeStamp— when event firedtransitionType— how navigation was triggered (link, typed, reload, etc.)
When to Use
- Track page loads for analytics or logging
- Detect SPA navigations (
onHistoryStateUpdated) - Frame-aware content script injection
- Page load timing measurement
- URL-filtered event processing (more efficient than
tabs.onUpdated)
When NOT to Use
- If you only need to know when tabs change — use
chrome.tabs.onUpdatedwithtabspermission - If you need to block/modify requests — use
declarativeNetRequest
Runtime Check
import { checkPermission } from '@theluckystrike/webext-permissions';
const granted = await checkPermission('webNavigation');
Cross-References
- Guide:
docs/guides/web-navigation.md - Related:
docs/permissions/tabs.md,docs/permissions/webRequest.md
Frequently Asked Questions
How do I track page navigations?
Use chrome.webNavigation API to receive events when frames navigate, complete loading, or encounter errors.
Can I block navigations with webNavigation?
No, webNavigation is for tracking only. To block or modify navigations, use declarativeNetRequest or webRequest. —
Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.
No previous article
No next article