Migrating from BrowserView to WebContentsView
BrowserView has been deprecated since Electron 30 and is replaced by WebContentView. Thankfully, migrating is fairly painless.
Electron is moving from BrowserView to WebContentsView to align with Chromium’s UI framework, the Views API. WebContentsView offers a reusable view directly tied to Chromium’s rendering pipeline, simplifying future upgrades and opening up the possibility for developers to integrate non-web UI elements to their Electron apps. By adopting WebContentsView, applications are not only prepared for upcoming updates but also benefit from reduced code complexity and fewer potential bugs in the long run.
Developers familiar with BrowserWindows and BrowserViews should note that BrowserWindow and WebContentsView are subclasses inheriting from the BaseWindow and View base classes, respectively. To fully understand the available instance variables and methods, be sure to consult the documentation for these base classes.
Migration steps
1. Upgrade Electron to 30.0.0 or higher
Electron releases may contain breaking changes that affect your application. It’s a good idea to test and land the Electron upgrade on your app first before proceeding with the rest of this migration. A list of breaking changes for each Electron major version can be found here as well as in the release notes for each major version on the Electron Blog.
2. Familiarize yourself with where your application uses BrowserViews
One way to do this is to search your codebase for new BrowserView(. This should give you a sense for how your application is using BrowserViews and how many call sites need to be migrated.
For the most part, each instance where your app instantiates new BrowserViews can be migrated in isolation from the others.
3. Migrate each usage of BrowserView
-
Migrate the instantiation. This should be fairly straightforward because WebContentsView and BrowserView’s constructors have essentially the same shape. Both accept WebPreferences via the
webPreferencesparam.- this.tabBar = new BrowserView({
+ this.tabBar = new WebContentsView({infoBy default,
WebContentsViewinstantiates with a white background, whileBrowserViewinstantiates with a transparent background. To get a transparent background inWebContentsView, set its background color to an RGBA hex value with an alpha (opaqueness) channel set to00:+ this.webContentsView.setBackgroundColor("#00000000"); -
Migrate where the
BrowserViewgets added to its parent window.- this.browserWindow.addBrowserView(this.tabBar)
+ this.browserWindow.contentView.addChildView(this.tabBar); -
Migrate
BrowserViewinstance method calls on the parent window.Old Method New Method Notes win.setBrowserViewwin.contentView.removeChildView+win.contentView.addChildViewwin.getBrowserViewwin.contentView.childrenwin.removeBrowserViewwin.contentView.removeChildViewwin.setTopBrowserViewwin.contentView.addChildViewCalling addChildViewon an existing view reorders it to the top.win.getBrowserViewswin.contentView.children -
Migrate the
setAutoResizeinstance method to a resize listener.- this.browserView.setAutoResize({
- vertical: true,
- })
+ this.browserWindow.on('resize', () => {
+ if (!this.browserWindow || !this.webContentsView) {
+ return;
+ }
+ const bounds = this.browserWindow.getBounds();
+ this.webContentsView.setBounds({
+ x: 0,
+ y: 0,
+ width: bounds.width,
+ height: bounds.height,
+ });
+ });tipAll existing usage of
browserView.webContentsand instance methodsbrowserView.setBounds,browserView.getBounds, andbrowserView.setBackgroundColordo not need to be migrated and should work with aWebContentsViewinstance out of the box!
4. Test and commit your changes
Running into issues? Check the WebContentsView tag on Electron's issue tracker to see if the issue you're encountering has been reported. If you don't see your issue there, feel free to add a new bug report. Including testcase gists will help us better triage your issue!
Congrats, you’ve migrated onto WebContentsViews! 🎉
