recursal/MDN huggingface dataset:
webNavigation.onDOMContentLoaded
================================

Fired when the DOMContentLoaded event is fired in the page. At this point the document is loaded and parsed, and the DOM is fully constructed, but linked resources such as images, stylesheets and subframes may not yet be loaded.

Syntax
------


```js
browser.webNavigation.onDOMContentLoaded.addListener(
  listener,                   // function
  filter                      // optional object
)
browser.webNavigation.onDOMContentLoaded.removeListener(listener)
browser.webNavigation.onDOMContentLoaded.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`details`

`object`. Details about the navigation event. See the details section for more information.


`filter` Optional

`object`. An object containing a single property `url`, which is an `Array` of `events.UrlFilter` objects. If you include this parameter, then the event fires only for transitions to URLs which match at least one `UrlFilter` in the array. If you omit this parameter, the event fires for all transitions.

Additional objects
------------------

### details

`tabId`

`integer`. The ID of the tab in which the navigation has occurred.

`url`

`string`. The URL to which the given frame has navigated.

`processId` Optional 
Deprecated

`integer`. This value is not set in modern browsers. When it was set, it represented the ID of the process running the renderer for this tab.

`frameId`

`integer`. Frame in which the navigation is occurring. `0` indicates that navigation happens in the tab's top-level browsing context, not in a nested `<iframe>`. A positive value indicates that navigation happens in a nested iframe. Frame IDs are unique for a given tab and process.

`timeStamp`

`number`. The time at which `DOMContentLoaded` was fired, in milliseconds since the epoch.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Logs the target URLs for `onDOMContentLoaded`, if the target URL's hostname contains "example.com" or starts with "developer".


```js
const filter = {
  url: [{ hostContains: "example.com" }, { hostPrefix: "developer" }],
};

function logOnDOMContentLoaded(details) {
  console.log(`onDOMContentLoaded: ${details.url}`);
}

browser.webNavigation.onDOMContentLoaded.addListener(
  logOnDOMContentLoaded,
  filter,
);
```


**Note:** This API is based on Chromium's `chrome.webNavigation` API. This documentation is derived from `web_navigation.json` in the Chromium code.
webNavigation.onBeforeNavigate
==============================

Fired when the browser is about to start a navigation event.

Syntax
------


```js
browser.webNavigation.onBeforeNavigate.addListener(
  listener,                   // function
  filter                      // optional object
)
browser.webNavigation.onBeforeNavigate.removeListener(listener)
browser.webNavigation.onBeforeNavigate.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`details`

`object`. Details about the navigation event. See the details section for more information.


`filter` Optional

`object`. An object containing a single property `url`, which is an `Array` of `events.UrlFilter` objects. If you include this parameter, then the event fires only for transitions to URLs which match at least one `UrlFilter` in the array. If you omit this parameter, the event fires for all transitions.

Additional objects
------------------

### details

`tabId`

`integer`. The ID of the tab in which the navigation is about to occur.

`url`

`string`. The URL to which the given frame will navigate.

`processId` Optional 
Deprecated

`integer`. This value is not set in modern browsers. When it was set, it represented the ID of the process running the renderer for this tab.

`frameId`

`integer`. Frame in which the navigation is about to occur. `0` indicates that navigation happens in the tab's top-level browsing context, not in a nested `<iframe>`. A positive value indicates that navigation happens in a nested iframe. Frame IDs are unique for a given tab and process.

`parentFrameId`

`integer`. ID of this frame's parent. Set to `-1` if this is a top-level frame.

`timeStamp`

`number`. The time when the browser is about to start the navigation, in milliseconds since the epoch.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Logs the target URLs for `onBeforeNavigate`, if the target's hostname contains "example.com" or starts with "developer".


```js
const filter = {
  url: [{ hostContains: "example.com" }, { hostPrefix: "developer" }],
};

function logOnBefore(details) {
  console.log(`onBeforeNavigate to: ${details.url}`);
}

browser.webNavigation.onBeforeNavigate.addListener(logOnBefore, filter);
```


**Note:** This API is based on Chromium's `chrome.webNavigation` API. This documentation is derived from `web_navigation.json` in the Chromium code.
webNavigation.onCompleted
=========================

Fired when a document, including the resources it refers to, is completely loaded and initialized. This is equivalent to the DOM `load` event.

Syntax
------


```js
browser.webNavigation.onCompleted.addListener(
  listener,                   // function
  filter                      // optional object
)
browser.webNavigation.onCompleted.removeListener(listener)
browser.webNavigation.onCompleted.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`details`

`object`. Details about the navigation event. See the details section for more information.


`filter` Optional

`object`. An object containing a single property `url`, which is an `Array` of `events.UrlFilter` objects. If you include this parameter, then the event fires only for transitions to URLs which match at least one `UrlFilter` in the array. If you omit this parameter, the event fires for all transitions.

Additional objects
------------------

### details

`tabId`

`integer`. The ID of the tab in which the navigation has occurred.

`url`

`string`. The URL to which the given frame has navigated.

`processId` Optional 
Deprecated

`integer`. This value is not set in modern browsers. When it was set, it represented the ID of the process running the renderer for this tab.

`frameId`

`integer`. Frame in which the navigation has occurred. `0` indicates that navigation happened in the tab's top-level browsing context, not in a nested `<iframe>`. A positive value indicates that navigation happened in a nested iframe. Frame IDs are unique for a given tab and process.

`timeStamp`

`number`. The time at which the page finished loading, in milliseconds since the epoch.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Logs the target URLs for `onCompleted`, if the target URL's hostname contains "example.com" or starts with "developer".


```js
const filter = {
  url: [{ hostContains: "example.com" }, { hostPrefix: "developer" }],
};

function logOnCompleted(details) {
  console.log(`onCompleted: ${details.url}`);
}

browser.webNavigation.onCompleted.addListener(logOnCompleted, filter);
```

### Example extensions

* navigation-stats

**Note:** This API is based on Chromium's `chrome.webNavigation` API. This documentation is derived from `web_navigation.json` in the Chromium code.
webNavigation.onErrorOccurred
=============================

Fired when an error occurs and the navigation is aborted. This can happen if either a network error occurred, or the user aborted the navigation.

Syntax
------


```js
browser.webNavigation.onErrorOccurred.addListener(
  listener,                   // function
  filter                      // optional object
)
browser.webNavigation.onErrorOccurred.removeListener(listener)
browser.webNavigation.onErrorOccurred.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

`addListener(listener, filter)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs.

The `listener` function is called with these arguments:

`details`

`object`. Details about the navigation event. **`details`** has the following properties:

`tabId`

`integer`. The ID of the tab in which the navigation was happening.

`url`

`string`. The URL to which the given frame was navigating.

`processId` Optional 
Deprecated

`integer`. This value is never set in modern browsers. It used to represent the ID of the process running the renderer for this tab.

`frameId`

`integer`. Frame in which the navigation was happening.

`0` indicates that navigation happened in the tab's top-level browsing context, not in a nested `<iframe>`.

A positive value indicates that navigation happened in a nested iframe.

Frame IDs are unique for a given tab and process.

`timeStamp`

`number`. The time at which the error occurred, in milliseconds since the epoch.

`error`

`string`. The error code. This is an internal error code, and is not guaranteed to stay the same or be consistent from one browser to another.


`filter` Optional

`object`. An object containing a single property `url`, which is an `Array` of `events.UrlFilter` objects.

If you include this parameter, then the event fires only for transitions to URLs which match at least one `UrlFilter` in the array.

If you omit this parameter, the event fires for all transitions.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Logs the target URLs for `onErrorOccurred`, if the target URL's `hostname` contains `"example.com"` or starts with `"developer"`.


```js
const filter = {
  url: [{ hostContains: "example.com" }, { hostPrefix: "developer" }],
};

function logOnErrorOccurred(details) {
  console.log(`onErrorOccurred: ${details.url}`);
  console.log(details.error);
}

browser.webNavigation.onErrorOccurred.addListener(logOnErrorOccurred, filter);
```


**Note:** This API is based on Chromium's `chrome.webNavigation` API. This documentation is derived from `web_navigation.json` in the Chromium code.
webNavigation.getFrame()
========================

Retrieves information about a particular frame. A frame may be the top-level frame in a tab or a nested `<iframe>`, and is uniquely identified by a tab ID and a frame ID.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingFrame = browser.webNavigation.getFrame(
  details                // object
)
```

### Parameters

`details`

`object`. Information about the frame to retrieve information about.

`tabId`

`integer`. The ID of the tab in which the frame is.

`processId` Optional 
Deprecated

`integer`. This value is not set in modern browsers. When it was set, it represented the ID of the process running the renderer for this tab.

`frameId`

`integer`. The ID of the frame in the given tab.


### Return value

A `Promise` that will be fulfilled with an object containing the following properties:

`errorOccurred`

`boolean`. True if the last navigation in this frame was interrupted by an error, i.e. the `onErrorOccurred` event fired.

`url`

`string`. The URL currently associated with this frame, if the frame identified by `frameId` existed at one point in the tab identified by `tabId`. The fact that a URL is associated with a given `frameId` does not imply that the corresponding frame still exists.

`parentFrameId`

`integer`. ID of this frame's parent. This is -1 if there is no parent frame: that is, if this frame is the top-level browsing context in the tab.

If the tab is discarded, the promise will instead resolve with a `null` value. If the specified tab or frame ID could not be found, or some other error occurs, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
function onGot(frameInfo) {
  console.log(frameInfo);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let gettingFrame = browser.webNavigation.getFrame({
  tabId: 19,
  frameId: 1537,
});

// Edge specific - processId is required not optional, must be integer not null
//let gettingFrame = browser.webNavigation.getFrame({ tabId: 19, processId: 0, frameId: 1537 });

gettingFrame.then(onGot, onError);
```


**Note:** This API is based on Chromium's `chrome.webNavigation` API. This documentation is derived from `web_navigation.json` in the Chromium code.
webNavigation.getAllFrames()
============================

Given a tab ID, retrieves information about all the frames it contains.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingFrames = browser.webNavigation.getAllFrames(
  details                // object
)
```

### Parameters

`details`

`object`. Information about the tab to retrieve all frames from.

`tabId`

`integer`. The ID of the tab.


### Return value

A `Promise` that will be fulfilled with an array of objects, each of which has the following properties:

`errorOccurred`

`boolean`. True if the last navigation in this frame was interrupted by an error, i.e. the `onErrorOccurred` event fired.

`processId` Optional 
Deprecated

`integer`. This value is not set in modern browsers. When it was set, it represented the ID of the process running the renderer for this tab.

`frameId`

`integer`. The ID of the frame. If this is the main frame, then `frameId` is zero.

`parentFrameId`

`integer`. ID of this frame's parent. This is -1 if there is no parent frame: that is, if this frame is the top-level browsing context in the tab.

`url`

`string`. The URL currently associated with this frame.

If the tab is discarded, the promise will instead resolve with a `null` value. If the specified tab could not be found, or some other error occurs, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This code logs the URLs of all frames in the active tab, when the user clicks a browser action:


```js
function logFrameInfo(framesInfo) {
  for (const frameInfo of framesInfo) {
    console.log(frameInfo);
  }
}

function onError(error) {
  console.error(`Error: ${error}`);
}

function logAllFrames(tabs) {
  browser.webNavigation
    .getAllFrames({
      tabId: tabs[0].id,
    })
    .then(logFrameInfo, onError);
}

browser.browserAction.onClicked.addListener(() => {
  browser.tabs
    .query({
      currentWindow: true,
      active: true,
    })
    .then(logAllFrames, onError);
});
```


**Note:** This API is based on Chromium's `chrome.webNavigation` API. This documentation is derived from `web_navigation.json` in the Chromium code.
webNavigation.TransitionType
============================

Cause of the navigation: for example, the user clicked a link, or typed an address, or clicked a bookmark.

Note that many values here are not currently supported in Firefox: see the browser compatibility table for details.

Type
----

Values of this type are strings. Possible values are:

"link"

The user clicked a link in another page.

"typed"

The user typed the URL into the address bar. This is also used if the user started typing into the address bar, then selected a URL from the suggestions it offered. See also "generated".

"auto\_bookmark"

The user clicked a bookmark or an item in the browser history.

"auto\_subframe"

Any nested iframes that are automatically loaded by their parent.

"manual\_subframe"

Any nested iframes that are loaded as an explicit user action. Loading such an iframe will generate an entry in the back/forward navigation list.

"generated"

The user started typing in the address bar, then clicked on a suggested entry that didn't contain a URL.

"start\_page"

The page was passed to the command line or is the start page.

"form\_submit"

The user submitted a form. Note that in some situations, such as when a form uses a script to submit its contents, submitting a form does not result in this transition type.

"reload"

The user reloaded the page, using the Reload button or by pressing Enter in the address bar. This is also used for session restore and reopening closed tabs.

"keyword"

The URL was generated using a keyword search configured by the user.

"keyword\_generated"

Corresponds to a visit generated for a keyword.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.webNavigation` API. This documentation is derived from `web_navigation.json` in the Chromium code.
webNavigation.TransitionQualifier
=================================

Extra information about a transition. Note that many values here are not currently supported in Firefox: see the browser compatibility table for details.

Type
----

Values of this type are strings. Possible values are:

"client\_redirect"

Redirect(s) caused by JavaScript running in the page or a "refresh" pragma in the page's meta tag.

"server\_redirect"

Redirect(s) caused by a 3XX HTTP status code sent from the server.

"forward\_back"

The user used the forward or back button to trigger the navigation.

"from\_address\_bar"

The user triggered the navigation from the address bar.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.webNavigation` API. This documentation is derived from `web_navigation.json` in the Chromium code.
find.removeHighlighting()
=========================

Remove any highlighting of a previous search that was applied by a previous call to `find.highlightResults()`, or by the browser's native UI.

Syntax
------


```js
browser.find.removeHighlighting()
```

### Parameters

None.

### Return value

None.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
browser.find.removeHighlighting();
```
find.highlightResults()
=======================

Highlights the results of a previous call to `find.find()`.

When an extension calls `find()`, the matches are not highlighted automatically, but they are stored by the browser. Call `highlightResults()` to highlight them.

Note that the stored results are global across all extensions, so for example, if extension A calls `find("apple")`, then extension B calls `find("banana")`, then if extension A calls `highlightResults()`, the results for "banana" will be highlighted.

Syntax
------


```js
browser.find.highlightResults(
  options // optional object
)
```

### Parameters

`options` Optional

`object`. An object specifying additional options. It may take any of the following properties, all optional:

`tabId`

`integer`. ID of the tab to highlight. Defaults to the active tab.

`rangeIndex`

`integer`. Index of the range to highlight. Defaults to highlighting all ranges.

`noScroll`

`boolean`. Don't scroll to highlighted item. Defaults to `true`.


### Return value

None.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Search the active tab for "banana", log the number of matches, and highlight them:


```js
function found(results) {
  console.log(`There were: ${results.count} matches.`);
  if (results.count > 0) {
    browser.find.highlightResults();
  }
}

browser.find.find("banana").then(found);
```
extensionTypes.ImageFormat
==========================

The format of an image.

Type
----

Values of this type are strings. Possible values are: `"jpeg"`, `"png"`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.extensionTypes` API. This documentation is derived from `extension_types.json` in the Chromium code.
extensionTypes.ImageDetails
===========================

Details about the format, quality, area and scale of a captured image.

Type
----

Values of this type are objects. They contain the following properties:

`format` Optional

`extensionTypes.ImageFormat`. The format of the resulting image. Default is `"png"`.

`quality` Optional

`integer`. When format is `"jpeg"`, this controls the quality of the resulting image. It is a number between 0 and 100, which is converted to a value between 0 and 1 and then used as the `encoderOptions` argument to `HTMLCanvasElement.toDataURL()`. If it is omitted, 92 is used. As quality is decreased, the resulting image will have more visual artifacts, and the number of bytes needed to store it will decrease. This value is ignored for PNG images.

`rect` Optional

An `object` specifying the area of the document to capture, in CSS pixels, relative to the page. All properties default to `0`. The properties are:

* `x`: The coordinate of the left side of the rectangle.
* `y`: The coordinate of the top side of the rectangle.
* `width`: The width of the rectangle.
* `height`: The height of the rectangle.

This option was introduced in Firefox 82. If omitted, the currently visible viewport is captured.

`scale` Optional

`number`. The scale to render at, defaults to `devicePixelRatio`. This option was introduced in Firefox 82.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.extensionTypes` API. This documentation is derived from `extension_types.json` in the Chromium code.