This page is part of the documentation for the Chrome Apps platform, which was deprecated in 2020. It remains supported for Enterprise and Education customers on ChromeOS until at least Jan 2025. Learn more about migrating your app.

chrome.webviewTag

Description

Use the webview tag to actively load live content from the web over the network and embed it in your Chrome App. Your app can control the appearance of the webview and interact with the web content, initiate navigations in an embedded web page, react to error events that happen within it, and more (see Usage).

Permissions

webview

Types

ClearDataOptions

Options that determine what data should be cleared by clearData.

Properties

since

number optional

Clear data accumulated on or after this date, represented in milliseconds since the epoch (accessible via the getTime method of the JavaScript Date object). If absent, defaults to 0 (which would remove all browsing data).

ClearDataTypeSet

A set of data types. Missing properties are interpreted as false.

Properties

appcache

boolean optional

Websites' appcaches.
cache

boolean optional

Chrome 44+

Since Chrome 43. The browser's cache. Note: when removing data, this clears the entire cache; it is not limited to the range you specify.
cookies

boolean optional

The partition's cookies.
fileSystems

boolean optional

Websites' filesystems.
indexedDB

boolean optional

Websites' IndexedDB data.
localStorage

boolean optional

Websites' local storage data.
persistentCookies

boolean optional

Chrome 58+

The partition's persistent cookies.
sessionCookies

boolean optional

Chrome 58+

The partition's session cookies.
webSQL

boolean optional

Websites' WebSQL data.

ContentScriptDetails

Chrome 44+

Details of the content script to inject. Refer to the content scripts documentation for more details.

Properties

all_frames

boolean optional

If all_frames is true, this implies that the JavaScript or CSS should be injected into all frames of current page. By default, all_frames is false and the JavaScript or CSS is only injected into the top frame.
css

InjectionItems optional

The CSS code or a list of CSS files to be injected into matching pages. These are injected in the order they appear, before any DOM is constructed or displayed for the page.
exclude_globs

string[] optional

Applied after matches to exclude URLs that match this glob. Intended to emulate the @exclude Greasemonkey keyword.
exclude_matches

string[] optional

Excludes pages that this content script would otherwise be injected into.
include_globs

string[] optional

Applied after matches to include only those URLs that also match this glob. Intended to emulate the @include Greasemonkey keyword.
js

InjectionItems optional

The JavaScript code or a list of JavaScript files to be injected into matching pages. These are injected in the order they appear.
match_about_blank

boolean optional

Whether to insert the content script on about:blank and about:srcdoc. Content scripts will only be injected on pages when their inherit URL is matched by one of the declared patterns in the matches field. The inherit URL is the URL of the document that created the frame or window. Content scripts cannot be inserted in sandboxed frames.
matches

string[]

Specifies which pages this content script will be injected into.
name

string

The name of the content script to inject.
run_at

RunAt optional

The soonest that the JavaScript or CSS will be injected into the tab. Defaults to "document_idle".

ContentWindow

Messaging handle to a guest window.

Properties

postMessage

void

Posts a message to the embedded web content as long as the embedded content is displaying a page from the target origin. This method is available once the page has completed loading. Listen for the contentload event and then call the method.

The guest will be able to send replies to the embedder by posting message to event.source on the message event it receives.

This API is identical to the HTML5 postMessage API for communication between web pages. The embedder may listen for replies by adding a message event listener to its own frame.

The postMessage function looks like:
```
(message: any, targetOrigin: string) => {...}
```
- message
  
  any
  
  Message object to send to the guest.
- targetOrigin
  
  string
  
  Specifies what the origin of the guest window must be for the event to be dispatched.

ContextMenuCreateProperties

Chrome 44+

Properties

checked

boolean optional

The initial state of a checkbox or radio item: true for selected and false for unselected. Only one radio item can be selected at a time in a given group of radio items.
contexts

[ContextType, ...ContextType[]] optional

List of contexts this menu item will appear in. Defaults to ['page'] if not specified.
documentUrlPatterns

string[] optional

Lets you restrict the item to apply only to documents whose URL matches one of the given patterns. (This applies to frames as well.) For details on the format of a pattern, see Match Patterns.
enabled

boolean optional

Whether this context menu item is enabled or disabled. Defaults to true.
id

string optional

The unique ID to assign to this item. Mandatory for event pages. Cannot be the same as another ID for this extension.
parentId

string | number optional

The ID of a parent menu item; this makes the item a child of a previously added item.
targetUrlPatterns

string[] optional

Similar to documentUrlPatterns, but lets you filter based on the src attribute of img/audio/video tags and the href of anchor tags.
title

string optional

The text to be displayed in the item; this is required unless type is 'separator'. When the context is 'selection', you can use %s within the string to show the selected text. For example, if this parameter's value is "Translate '%s' to Pig Latin" and the user selects the word "cool", the context menu item for the selection is "Translate 'cool' to Pig Latin".
type

ItemType optional

The type of menu item. Defaults to 'normal' if not specified.
onclick

void optional

A function that will be called back when the menu item is clicked.

The onclick function looks like:
```
(info: OnClickData) => {...}
```
- info
  
  OnClickData
  
  Information about the item clicked and the context where the click happened.

ContextMenus

Chrome 44+

Properties

onShow

Event<functionvoidvoid>

Fired before showing a context menu on this webview. Can be used to disable this context menu by calling event.preventDefault().

The onShow.addListener function looks like:
```
(callback: function) => {...}
```
- callback
  
  function
  
  The callback parameter looks like:
```
(event: object) => void
```
  - event
    
    object
    
    preventDefault
    
    void
    
    Call this to prevent showing the context menu.
    
    The preventDefault function looks like:
    () => {...}
create

void

Creates a new context menu item. Note that if an error occurs during creation, you may not find out until the creation callback fires (the details will be in runtime.lastError).

The create function looks like:
```
(createProperties: object, callback?: function) => {...}
```
- createProperties
  
  object
  
  The properties used to create the item
- callback
  
  function optional
  
  The callback parameter looks like:
```
() => void
```
- returns
  string | number
  
  The ID of the newly created item.
remove

void

Removes a context menu item.

The remove function looks like:
```
(menuItemId: string | number, callback?: function) => {...}
```
- menuItemId
  
  string | number
  
  The ID of the context menu item to remove.
- callback
  
  function optional
  
  The callback parameter looks like:
```
() => void
```
removeAll

void

Removes all context menu items added to this webview.

The removeAll function looks like:
```
(callback?: function) => {...}
```
- callback
  
  function optional
  
  The callback parameter looks like:
```
() => void
```
update

void

Updates a previously created context menu item.

The update function looks like:
```
(id: string | number, updateProperties: object, callback?: function) => {...}
```
- id
  
  string | number
  
  The ID of the item to update.
- updateProperties
  
  object
  
  The properties to update. Accepts the same values as the create function.
- callback
  
  function optional
  
  The callback parameter looks like:
```
() => void
```

ContextMenuUpdateProperties

Chrome 44+

Properties

checked

boolean optional

The state of a checkbox or radio item: true for selected and false for unselected. Only one radio item can be selected at a time in a given group of radio items.
contexts

[ContextType, ...ContextType[]] optional

List of contexts this menu item will appear in.
documentUrlPatterns

string[] optional

Lets you restrict the item to apply only to documents whose URL matches one of the given patterns. (This applies to frames as well.) For details on the format of a pattern, see Match Patterns.
enabled

boolean optional

Whether this context menu item is enabled or disabled.
parentId

string | number optional

The ID of a parent menu item; this makes the item a child of a previously added item. Note: You cannot change an item to be a child of one of its own descendants.
targetUrlPatterns

string[] optional

Similar to documentUrlPatterns, but lets you filter based on the src attribute of img/audio/video tags and the href of anchor tags.
title

string optional

The text to be displayed in the item
type

ItemType optional

The type of menu item.
onclick

void optional

A function that will be called back when the menu item is clicked.

The onclick function looks like:
```
(info: OnClickData) => {...}
```
- info
  
  OnClickData
  
  Information about the item clicked and the context where the click happened.

ContextType

Chrome 44+

The different contexts a menu can appear in. Specifying 'all' is equivalent to the combination of all other contexts.

Enum

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

DialogController

Interface attached to dialog DOM events.

Properties

cancel

void

Reject the dialog. Equivalent to clicking Cancel in a confirm or prompt dialog.

The cancel function looks like:
```
() => {...}
```
ok

void

Accept the dialog. Equivalent to clicking OK in an alert, confirm, or prompt dialog.

The ok function looks like:
```
(response?: string) => {...}
```
- response
  
  string optional
  
  The response string to provide to the guest when accepting a prompt dialog.

DownloadPermissionRequest

The type of request object which accompanies a download permissionrequest DOM event.

Properties

requestMethod

string

The HTTP request type (e.g. GET) associated with the download request.
url

string

The requested download URL.
allow

void

Allow the permission request.

The allow function looks like:
```
() => {...}
```
deny

void

Deny the permission request. This is the default behavior if allow is not called.

The deny function looks like:
```
() => {...}
```

FileSystemPermissionRequest

The type of request object which accompanies a filesystem permissionrequest DOM event.

Properties

url

string

The URL of the frame requesting access to local file system.
allow

void

Allow the permission request.

The allow function looks like:
```
() => {...}
```
deny

void

Deny the permission request.

The deny function looks like:
```
() => {...}
```

FindCallbackResults

Contains all of the results of the find request.

Properties

activeMatchOrdinal

number

The ordinal number of the current match.
canceled

boolean

Indicates whether this find request was canceled.
numberOfMatches

number

The number of times searchText was matched on the page.
selectionRect

SelectionRect

Describes a rectangle around the active match in screen coordinates.

FindOptions

Options for the find request.

Properties

backward

boolean optional

Flag to find matches in reverse order. The default value is false.
matchCase

boolean optional

Flag to match with case-sensitivity. The default value is false.

FullscreenPermissionRequest

Chrome 43+

The type of request object which accompanies a fullscreen permissionrequest DOM event.

Properties

origin

string

The origin of the frame inside the webview that initiated the fullscreen request.
allow

void

Allow the permission request.

The allow function looks like:
```
() => {...}
```
deny

void

Deny the permission request.

The deny function looks like:
```
() => {...}
```

GeolocationPermissionRequest

The type of request object which accompanies a geolocation permissionrequest DOM event.

Properties

url

string

The URL of the frame requesting access to geolocation data.
allow

void

Allow the permission request.

The allow function looks like:
```
() => {...}
```
deny

void

Deny the permission request. This is the default behavior if allow is not called.

The deny function looks like:
```
() => {...}
```

HidPermissionRequest

Chrome 125+

The type of request object which accompanies an hid permissionrequest DOM event.

Properties

url

string

The URL of the frame requesting access to the HID API.
allow

void

Allow the permission request.

The allow function looks like:
```
() => {...}
```
deny

void

Deny the permission request. This is the default behavior if allow is not called.

The deny function looks like:
```
() => {...}
```

InjectDetails

Details of the script or CSS to inject. Either the code or the file property must be set, but both may not be set at the same time.

Properties

code

string optional

JavaScript or CSS code to inject.

Warning: Be careful using the code parameter. Incorrect use of it may open your app to cross site scripting attacks.
file

string optional

JavaScript or CSS file to inject.

InjectionItems

Chrome 44+

The type of injection item: code or a set of files.

Properties

code

string optional

JavaScript code or CSS to be injected into matching pages.
files

string[] optional

The list of JavaScript or CSS files to be injected into matching pages. These are injected in the order they appear in this array.

LoadPluginPermissionRequest

The type of request object which accompanies a loadplugin permissionrequest DOM event.

Properties

identifier

string

The plugin's identifier string.
name

string

The plugin's display name.
allow

void

Allow the permission request. This is the default behavior if deny is not called..

The allow function looks like:
```
() => {...}
```
deny

void

Deny the permission request.

The deny function looks like:
```
() => {...}
```

MediaPermissionRequest

The type of request object which accompanies a media permissionrequest DOM event.

Properties

url

string

The URL of the frame requesting access to user media.
allow

void

Allow the permission request.

The allow function looks like:
```
() => {...}
```
deny

void

Deny the permission request. This is the default behavior if allow is not called.

The deny function looks like:
```
() => {...}
```

NewWindow

Interface attached to newwindow DOM events.

Properties

attach

void

Attach the requested target page to an existing webview element.

The attach function looks like:
```
(webview: object) => {...}
```
- webview
  
  object
  
  The webview element to which the target page should be attached.
discard

void

Cancel the new window request.

The discard function looks like:
```
() => {...}
```

PointerLockPermissionRequest

The type of request object which accompanies a pointerLock permissionrequest DOM event.

Properties

lastUnlockedBySelf

boolean

Whether or not the requesting frame was the most recent client to hold pointer lock.
url

string

The URL of the frame requesting pointer lock.
userGesture

boolean

Whether or not pointer lock was requested as a result of a user input gesture.
allow

void

Allow the permission request.

The allow function looks like:
```
() => {...}
```
deny

void

Deny the permission request. This is the default behavior if allow is not called.

The deny function looks like:
```
() => {...}
```

SelectionRect

Describes a rectangle in screen coordinates.

The containment semantics are array-like; that is, the coordinate (left, top) is considered to be contained by the rectangle, but the coordinate (left + width, top) is not.

Properties

height

number

Height of the rectangle.
left

number

Distance from the left edge of the screen to the left edge of the rectangle.
top

number

Distance from the top edge of the screen to the top edge of the rectangle.
width

number

Width of the rectangle.

WebRequestEventInterface

Chrome 44+

Interface which provides access to webRequest events on the guest page. See the chrome.webRequest extensions API for details on webRequest life cycle and related concepts. Note: The chrome.webRequest.onActionIgnored event is not supported for webviews.

To illustrate how usage differs from the extensions webRequest API, consider the following example code which blocks any guest requests for URLs which match *://www.evil.com/*:

webview.request.onBeforeRequest.addListener(
  function(details) { return {cancel: true}; },
  {urls: ["*://www.evil.com/*"]},
  ["blocking"]);

Additionally, this interface supports declarative webRequest rules through onRequest and onMessage events. See declarativeWebRequest for API details.

Note that conditions and actions for declarative webview webRequests should be instantiated from their chrome.webViewRequest.* counterparts. The following example code declaratively blocks all requests to "example.com" on the webview myWebview:

var rule = {
  conditions: [
    new chrome.webViewRequest.RequestMatcher({ url: { hostSuffix: 'example.com' } })
  ],
  actions: [ new chrome.webViewRequest.CancelRequest() ]
};
myWebview.request.onRequest.addRules([rule]);

ZoomMode

Chrome 43+

Defines the how zooming is handled in the webview.

Enum

"per-origin"
Zoom changes will persist in the zoomed page's origin, i.e. all other webviews in the same partition that are navigated to that same origin will be zoomed as well. Moreover, per-origin zoom changes are saved with the origin, meaning that when navigating to other pages in the same origin, they will all be zoomed to the same zoom factor.

"per-view"
Zoom changes only take effect in this webview, and zoom changes in other webviews will not affect the zooming of this webview. Also, per-view zoom changes are reset on navigation; navigating a webview will always load pages with their per-origin zoom factors (within the scope of the partition).

"disabled"
Disables all zooming in the webview. The content will revert to the default zoom level, and all attempted zoom changes will be ignored.

Properties

contentWindow

Object reference which can be used to post messages into the guest page.

Type

ContentWindow

contextMenus

Chrome 44+

Similar to chrome's ContextMenus API, but applies to webview instead of browser. Use the webview.contextMenus API to add items to webview's context menu. You can choose what types of objects your context menu additions apply to, such as images, hyperlinks, and pages.

Type

ContextMenus

request

Interface which provides access to webRequest events on the guest page.

Type

WebRequestEventInterface

Methods

addContentScripts()

Chrome 44+

chrome.webviewTag.addContentScripts(
  contentScriptList: [ContentScriptDetails, ...ContentScriptDetails[]],
)

Adds content script injection rules to the webview. When the webview navigates to a page matching one or more rules, the associated scripts will be injected. You can programmatically add rules or update existing rules.

The following example adds two rules to the webview: 'myRule' and 'anotherRule'.

webview.addContentScripts([
  {
    name: 'myRule',
    matches: ['http://www.foo.com/*'],
    css: { files: ['mystyles.css'] },
    js: { files: ['jquery.js', 'myscript.js'] },
    run_at: 'document_start'
  },
  {
    name: 'anotherRule',
    matches: ['http://www.bar.com/*'],
    js: { code: "document.body.style.backgroundColor = 'red';" },
    run_at: 'document_end'
  }]);
 ...

// Navigates webview.
webview.src = 'http://www.foo.com';

You can defer addContentScripts call until you needs to inject scripts.

The following example shows how to overwrite an existing rule.

webview.addContentScripts([{
    name: 'rule',
    matches: ['http://www.foo.com/*'],
    js: { files: ['scriptA.js'] },
    run_at: 'document_start'}]);

// Do something.
webview.src = 'http://www.foo.com/*';
 ...
// Overwrite 'rule' defined before.
webview.addContentScripts([{
    name: 'rule',
    matches: ['http://www.bar.com/*'],
    js: { files: ['scriptB.js'] },
    run_at: 'document_end'}]);

If webview has been naviagted to the origin (e.g., foo.com) and calls webview.addContentScripts to add 'myRule', you need to wait for next navigation to make the scripts injected. If you want immediate injection, executeScript will do the right thing.

Rules are preserved even if the guest process crashes or is killed or even if the webview is reparented.

Refer to the content scripts documentation for more details.

Parameters

contentScriptList

[ContentScriptDetails, ...ContentScriptDetails[]]

Details of the content scripts to add.

back()

chrome.webviewTag.back(
  callback?: function,
)

Navigates backward one history entry if possible. Equivalent to go(-1).

Parameters

callback

function optional

Chrome 44+

The callback parameter looks like:
```
(success: boolean) => void
```
- success
  
  boolean
  
  Indicates whether the navigation was successful.

canGoBack()

chrome.webviewTag.canGoBack()

Indicates whether or not it is possible to navigate backward through history. The state of this function is cached, and updated before each loadcommit, so the best place to call it is on loadcommit.

Returns

boolean

canGoForward()

chrome.webviewTag.canGoForward()

Indicates whether or not it is possible to navigate forward through history. The state of this function is cached, and updated before each loadcommit, so the best place to call it is on loadcommit.

Returns

boolean

captureVisibleRegion()

Chrome 50+

chrome.webviewTag.captureVisibleRegion(
  options?: ImageDetails,
  callback: function,
)

Captures the visible region of the webview.

Parameters

options

ImageDetails optional
callback

function

The callback parameter looks like:
```
(dataUrl: string) => void
```
- dataUrl
  
  string
  
  A data URL which encodes an image of the visible area of the captured tab. May be assigned to the 'src' property of an HTML Image element for display.

clearData()

chrome.webviewTag.clearData(
  options: ClearDataOptions,
  types: ClearDataTypeSet,
  callback?: function,
)

Clears browsing data for the webview partition.

Parameters

options

ClearDataOptions

Options determining which data to clear.
types

ClearDataTypeSet

The types of data to be cleared.
callback

function optional

The callback parameter looks like:
```
() => void
```

executeScript()

chrome.webviewTag.executeScript(
  details: InjectDetails,
  callback?: function,
)

Injects JavaScript code into the guest page.

The following sample code uses script injection to set the guest page's background color to red:

webview.executeScript({ code: "document.body.style.backgroundColor = 'red'" });

Parameters

details

InjectDetails

Details of the script to run.
callback

function optional

The callback parameter looks like:
```
(result?: any[]) => void
```
- result
  
  any[] optional
  
  The result of the script in every injected frame.

find()

chrome.webviewTag.find(
  searchText: string,
  options?: FindOptions,
  callback?: function,
)

Initiates a find-in-page request.

Parameters

searchText

string

The string to find in the page.
options

FindOptions optional

Options for the find request.
callback

function optional

The callback parameter looks like:
```
(results?: FindCallbackResults) => void
```
- results
  
  FindCallbackResults optional
  
  Contains all of the results of the find request. results can be omitted if it is not utilized in the callback function body; for example, if the callback is only used to discern when the find request has completed.

forward()

chrome.webviewTag.forward(
  callback?: function,
)

Navigates forward one history entry if possible. Equivalent to go(1).

Parameters

callback

function optional

Chrome 44+

The callback parameter looks like:
```
(success: boolean) => void
```
- success
  
  boolean
  
  Indicates whether the navigation was successful.

getAudioState()

Chrome 62+

chrome.webviewTag.getAudioState(
  callback: function,
)

Queries audio state.

Parameters

callback

function

The callback parameter looks like:
```
(audible: boolean) => void
```
- audible
  
  boolean

getProcessId()

chrome.webviewTag.getProcessId()

Returns Chrome's internal process ID for the guest web page's current process, allowing embedders to know how many guests would be affected by terminating the process. Two guests will share a process only if they belong to the same app and have the same storage partition ID. The call is synchronous and returns the embedder's cached notion of the current process ID. The process ID isn't the same as the operating system's process ID.

Returns

number

getUserAgent()

chrome.webviewTag.getUserAgent()

Returns the user agent string used by the webview for guest page requests.

Returns

string

getZoom()

chrome.webviewTag.getZoom(
  callback: function,
)

Gets the current zoom factor.

Parameters

callback

function

The callback parameter looks like:
```
(zoomFactor: number) => void
```
- zoomFactor
  
  number
  
  The current zoom factor.

getZoomMode()

Chrome 43+

chrome.webviewTag.getZoomMode(
  callback: function,
)

Gets the current zoom mode.

Parameters

callback

function

The callback parameter looks like:
```
(ZoomMode: ZoomMode) => void
```
- ZoomMode
  
  ZoomMode
  
  The webview's current zoom mode.

go()

chrome.webviewTag.go(
  relativeIndex: number,
  callback?: function,
)

Navigates to a history entry using a history index relative to the current navigation. If the requested navigation is impossible, this method has no effect.

Parameters

relativeIndex

number

Relative history index to which the webview should be navigated. For example, a value of 2 will navigate forward 2 history entries if possible; a value of -3 will navigate backward 3 entries.
callback

function optional

The callback parameter looks like:
```
(success: boolean) => void
```
- success
  
  boolean
  
  Indicates whether the navigation was successful.

insertCSS()

chrome.webviewTag.insertCSS(
  details: InjectDetails,
  callback?: function,
)

Injects CSS into the guest page.

Parameters

details

InjectDetails

Details of the CSS to insert.
callback

function optional

The callback parameter looks like:
```
() => void
```

isAudioMuted()

Chrome 62+

chrome.webviewTag.isAudioMuted(
  callback: function,
)

Queries whether audio is muted.

Parameters

callback

function

The callback parameter looks like:
```
(muted: boolean) => void
```
- muted
  
  boolean

isSpatialNavigationEnabled()

Chrome 71+

chrome.webviewTag.isSpatialNavigationEnabled(
  callback: function,
)

Queries whether spatial navigation is enabled for the webview.

Parameters

callback

function

The callback parameter looks like:
```
(enabled: boolean) => void
```
- enabled
  
  boolean

isUserAgentOverridden()

chrome.webviewTag.isUserAgentOverridden()

Indicates whether or not the webview's user agent string has been overridden by webviewTag.setUserAgentOverride.

loadDataWithBaseUrl()

chrome.webviewTag.loadDataWithBaseUrl(
  dataUrl: string,
  baseUrl: string,
  virtualUrl?: string,
)

Loads a data URL with a specified base URL used for relative links. Optionally, a virtual URL can be provided to be shown to the user instead of the data URL.

Parameters

dataUrl

string

The data URL to load.
baseUrl

string

The base URL that will be used for relative links.
virtualUrl

string optional

The URL that will be displayed to the user (in the address bar).

print()

chrome.webviewTag.print()

Prints the contents of the webview. This is equivalent to calling scripted print function from the webview itself.

reload()

chrome.webviewTag.reload()

Reloads the current top-level page.

removeContentScripts()

Chrome 44+

chrome.webviewTag.removeContentScripts(
  scriptNameList?: string[],
)

Removes content scripts from a webview.

The following example removes "myRule" which was added before.

webview.removeContentScripts(['myRule']);

You can remove all the rules by calling:

webview.removeContentScripts();

Parameters

scriptNameList

string[] optional

A list of names of content scripts that will be removed. If the list is empty, all the content scripts added to the webview will be removed.

setAudioMuted()

Chrome 62+

chrome.webviewTag.setAudioMuted(
  mute: boolean,
)

Sets audio mute state of the webview.

Parameters

mute

boolean

Mute audio value

setSpatialNavigationEnabled()

Chrome 71+

chrome.webviewTag.setSpatialNavigationEnabled(
  enabled: boolean,
)

Sets spatial navigation state of the webview.

Parameters

enabled

boolean

Spatial navigation state value.

setUserAgentOverride()

chrome.webviewTag.setUserAgentOverride(
  userAgent: string,
)

Override the user agent string used by the webview for guest page requests. Overriding will cause the User-Agent Client Hint header values and the values returned by navigator.userAgentData to be empty for guest page requests this override is applied to.

Parameters

userAgent

string

The user agent string to use.

setZoom()

chrome.webviewTag.setZoom(
  zoomFactor: number,
  callback?: function,
)

Changes the zoom factor of the page. The scope and persistence of this change are determined by the webview's current zoom mode (see webviewTag.ZoomMode).

Parameters

zoomFactor

number

The new zoom factor.
callback

function optional

The callback parameter looks like:
```
() => void
```

setZoomMode()

Chrome 43+

chrome.webviewTag.setZoomMode(
  ZoomMode: ZoomMode,
  callback?: function,
)

Sets the zoom mode of the webview.

Parameters

ZoomMode

ZoomMode

Defines how zooming is handled in the webview.
callback

function optional

The callback parameter looks like:
```
() => void
```

stop()

chrome.webviewTag.stop()

Stops loading the current webview navigation if in progress.

stopFinding()

chrome.webviewTag.stopFinding(
  action?: "clear" 
  | "keep" 
  | "activate" 
 ,
)

Ends the current find session (clearing all highlighting) and cancels all find requests in progress.

Parameters

action

"clear"
| "keep"
| "activate"
optional

Determines what to do with the active match after the find session has ended. clear will clear the highlighting over the active match; keep will keep the active match highlighted; activate will keep the active match highlighted and simulate a user click on that match. The default action is keep.

terminate()

chrome.webviewTag.terminate()

Forcibly kills the guest web page's renderer process. This may affect multiple webview tags in the current app if they share the same process, but it will not affect webview tags in other apps.

Events

close

chrome.webviewTag.close.addListener(
  callback: function,
)

Fired when the guest window attempts to close itself.

The following example code navigates the webview to about:blank when the guest attempts to close itself.

webview.addEventListener('close', function() {
  webview.src = 'about:blank';
});

Parameters

callback

function

The callback parameter looks like:
```
() => void
```

consolemessage

chrome.webviewTag.consolemessage.addListener(
  callback: function,
)

Fired when the guest window logs a console message.

The following example code forwards all log messages to the embedder's console without regard for log level or other properties.

webview.addEventListener('consolemessage', function(e) {
  console.log('Guest page logged a message: ', e.message);
});

Parameters

callback

function

The callback parameter looks like:

(level: number, message: string, line: number, sourceId: string) => void

level

number
message

string
line

number
sourceId

string

contentload

chrome.webviewTag.contentload.addListener(
  callback: function,
)

Fired when the guest window fires a load event, i.e., when a new document is loaded. This does not include page navigation within the current document or asynchronous resource loads.

The following example code modifies the default font size of the guest's body element after the page loads:

webview.addEventListener('contentload', function() {
  webview.executeScript({ code: 'document.body.style.fontSize = "42px"' });
});

Parameters

callback

function

The callback parameter looks like:
```
() => void
```

dialog

chrome.webviewTag.dialog.addListener(
  callback: function,
)

Fired when the guest window attempts to open a modal dialog via window.alert, window.confirm, or window.prompt.

Handling this event will block the guest process until each event listener returns or the dialog object becomes unreachable (if preventDefault() was called.)

The default behavior is to cancel the dialog.

Parameters

callback

function

The callback parameter looks like:

(messageType: "alert" 
  | "confirm" 
  | "prompt" 
 , messageText: string, dialog: DialogController) => void

messageType

"alert"
| "confirm"
| "prompt"
messageText

string
dialog

DialogController

exit

chrome.webviewTag.exit.addListener(
  callback: function,
)

Fired when the process rendering the guest web content has exited.

The following example code will show a farewell message whenever the guest page crashes:

webview.addEventListener('exit', function(e) {
  if (e.reason === 'crash') {
    webview.src = 'data:text/plain,Goodbye, world!';
  }
});

Parameters

callback

function

The callback parameter looks like:

(processID: number, reason: "normal" 
  | "abnormal" 
  | "crash" 
  | "kill" 
 ) => void

processID

number
reason

"normal"
| "abnormal"
| "crash"
| "kill"

findupdate

chrome.webviewTag.findupdate.addListener(
  callback: function,
)

Fired when new find results are available for an active find request. This might happen multiple times for a single find request as matches are found.

Parameters

callback

function

The callback parameter looks like:

(searchText: string, numberOfMatches: number, activeMatchOrdinal: number, selectionRect: SelectionRect, canceled: boolean, finalUpdate: string) => void

searchText

string
numberOfMatches

number
activeMatchOrdinal

number
selectionRect

SelectionRect
canceled

boolean
finalUpdate

string

loadabort

chrome.webviewTag.loadabort.addListener(
  callback: function,
)

Fired when a top-level load has aborted without committing. An error message will be printed to the console unless the event is default-prevented.

Note: When a resource load is aborted, a loadabort event will eventually be followed by a loadstop event, even if all committed loads since the last loadstop event (if any) were aborted.

Note: When the load of either an about URL or a JavaScript URL is aborted, loadabort will be fired and then the webview will be navigated to 'about:blank'.

Parameters

callback

function

The callback parameter looks like:

(url: string, isTopLevel: boolean, code: number, reason: "ERR_ABORTED" 
  | "ERR_INVALID_URL" 
  | "ERR_DISALLOWED_URL_SCHEME" 
  | "ERR_BLOCKED_BY_CLIENT" 
  | "ERR_ADDRESS_UNREACHABLE" 
  | "ERR_EMPTY_RESPONSE" 
  | "ERR_FILE_NOT_FOUND" 
  | "ERR_UNKNOWN_URL_SCHEME" 
 ) => void

url

string
isTopLevel

boolean
code

number
reason

"ERR_ABORTED"
| "ERR_INVALID_URL"
| "ERR_DISALLOWED_URL_SCHEME"
| "ERR_BLOCKED_BY_CLIENT"
| "ERR_ADDRESS_UNREACHABLE"
| "ERR_EMPTY_RESPONSE"
| "ERR_FILE_NOT_FOUND"
| "ERR_UNKNOWN_URL_SCHEME"

loadcommit

chrome.webviewTag.loadcommit.addListener(
  callback: function,
)

Fired when a load has committed. This includes navigation within the current document as well as subframe document-level loads, but does not include asynchronous resource loads.

Parameters

callback

function

The callback parameter looks like:
```
(url: string, isTopLevel: boolean) => void
```
- url
  
  string
- isTopLevel
  
  boolean

loadredirect

chrome.webviewTag.loadredirect.addListener(
  callback: function,
)

Fired when a top-level load request has redirected to a different URL.

Parameters

callback

function

The callback parameter looks like:
```
(oldUrl: string, newUrl: string, isTopLevel: boolean) => void
```
- oldUrl
  
  string
- newUrl
  
  string
- isTopLevel
  
  boolean

loadstart

chrome.webviewTag.loadstart.addListener(
  callback: function,
)

Fired when a load has begun.

Parameters

callback

function

The callback parameter looks like:
```
(url: string, isTopLevel: boolean) => void
```
- url
  
  string
- isTopLevel
  
  boolean

loadstop

chrome.webviewTag.loadstop.addListener(
  callback: function,
)

Fired when all frame-level loads in a guest page (including all its subframes) have completed. This includes navigation within the current document as well as subframe document-level loads, but does not include asynchronous resource loads. This event fires every time the number of document-level loads transitions from one (or more) to zero. For example, if a page that has already finished loading (i.e., loadstop already fired once) creates a new iframe which loads a page, then a second loadstop will fire when the iframe page load completes. This pattern is commonly observed on pages that load ads.

Note: When a committed load is aborted, a loadstop event will eventually follow a loadabort event, even if all committed loads since the last loadstop event (if any) were aborted.

Parameters

callback

function

The callback parameter looks like:
```
() => void
```

newwindow

chrome.webviewTag.newwindow.addListener(
  callback: function,
)

Fired when the guest page attempts to open a new browser window.

The following example code will create and navigate a new webview in the embedder for each requested new window:

webview.addEventListener('newwindow', function(e) {
  var newWebview = document.createElement('webview');
  document.body.appendChild(newWebview);
  e.window.attach(newWebview);
});

Parameters

callback

function

The callback parameter looks like:

(window: NewWindow, targetUrl: string, initialWidth: number, initialHeight: number, name: string, windowOpenDisposition: "ignore" 
  | "save_to_disk" 
  | "current_tab" 
  | "new_background_tab" 
  | "new_foreground_tab" 
  | "new_window" 
  | "new_popup" 
 ) => void

window

NewWindow
targetUrl

string
initialWidth

number
initialHeight

number
name

string
windowOpenDisposition

"ignore"
| "save_to_disk"
| "current_tab"
| "new_background_tab"
| "new_foreground_tab"
| "new_window"
| "new_popup"

permissionrequest

chrome.webviewTag.permissionrequest.addListener(
  callback: function,
)

Fired when the guest page needs to request special permission from the embedder.

The following example code will grant the guest page access to the webkitGetUserMedia API. Note that an app using this example code must itself specify audioCapture and/or videoCapture manifest permissions:

webview.addEventListener('permissionrequest', function(e) {
  if (e.permission === 'media') {
    e.request.allow();
  }
});

Parameters

callback

function

The callback parameter looks like:

(permission: "media" 
  | "geolocation" 
  | "pointerLock" 
  | "download" 
  | "loadplugin" 
  | "filesystem" 
  | "fullscreen" 
  | "hid" 
 , request: object) => void

permission

"media"
| "geolocation"
| "pointerLock"
| "download"
| "loadplugin"
| "filesystem"
| "fullscreen"
| "hid"
request

object

responsive

chrome.webviewTag.responsive.addListener(
  callback: function,
)

Fired when the process rendering the guest web content has become responsive again after being unresponsive.

The following example code will fade the webview element in or out as it becomes responsive or unresponsive:

webview.style.webkitTransition = 'opacity 250ms';
webview.addEventListener('unresponsive', function() {
  webview.style.opacity = '0.5';
});
webview.addEventListener('responsive', function() {
  webview.style.opacity = '1';
});

Parameters

callback

function

The callback parameter looks like:
```
(processID: number) => void
```
- processID
  
  number

sizechanged

chrome.webviewTag.sizechanged.addListener(
  callback: function,
)

Fired when the embedded web content has been resized via autosize. Only fires if autosize is enabled.

Parameters

callback

function

The callback parameter looks like:

(oldWidth: number, oldHeight: number, newWidth: number, newHeight: number) => void

oldWidth

number
oldHeight

number
newWidth

number
newHeight

number

unresponsive

chrome.webviewTag.unresponsive.addListener(
  callback: function,
)

Fired when the process rendering the guest web content has become unresponsive. This event will be generated once with a matching responsive event if the guest begins to respond again.

Parameters

callback

function

The callback parameter looks like:
```
(processID: number) => void
```
- processID
  
  number

zoomchange

chrome.webviewTag.zoomchange.addListener(
  callback: function,
)

Fired when the page's zoom changes.

Parameters

callback

function

The callback parameter looks like:
```
(oldZoomFactor: number, newZoomFactor: number) => void
```
- oldZoomFactor
  
  number
- newZoomFactor
  
  number