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​

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.

3. Migrate each usage of BrowserView​

1. Migrate the instantiation. This should be fairly straightforward because WebContentsView and BrowserView’s constructors have essentially the same shape. Both accept WebPreferences via the webPreferences param.

   - this.tabBar = new BrowserView({
   + this.tabBar = new WebContentsView({
   

   info

   By default, WebContentsView instantiates with a white background, while BrowserView instantiates with a transparent background. To get a transparent background in WebContentsView, set its background color to an RGBA hex value with an alpha (opaqueness) channel set to 00:

   + this.webContentsView.setBackgroundColor("#00000000");
   

2. Migrate where the BrowserView gets added to its parent window.

   - this.browserWindow.addBrowserView(this.tabBar)
   + this.browserWindow.contentView.addChildView(this.tabBar);
   

3. Migrate BrowserView instance method calls on the parent window.

   Old Method	New Method	Notes
   win.setBrowserView	win.contentView.removeChildView + win.contentView.addChildView
   win.getBrowserView	win.contentView.children
   win.removeBrowserView	win.contentView.removeChildView
   win.setTopBrowserView	win.contentView.addChildView	Calling addChildView on an existing view reorders it to the top.
   win.getBrowserViews	win.contentView.children

4. Migrate the setAutoResize instance 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,
   +    });
   +  });
   

   tip

   All existing usage of browserView.webContents and instance methods browserView.setBounds, browserView.getBounds , and browserView.setBackgroundColor do not need to be migrated and should work with a WebContentsView instance 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! 🎉