- Qt 6.10
- Qt WebEngine
- Qt WebEngine Features
- Qt 6.10.3 Reference Documentation

Overview ◦ Platform Notes

# Qt WebEngine Features

Qt WebEngine supports the following features:

- Audio and Video Codecs
- WebEngineDriver
- Chromium DevTools
- Client Certificates
- Custom Schemes
- Drag and Drop
- Favicon
- Fullscreen
- Hardware Acceleration
- HTML5 DRM
- HTML5 Geolocation
- HTML5 WebSockets
- HTTP/2 Protocol
- Local Storage
- Native Dialogs
- PDF File Viewing
- Page Lifecycle API
- Print to PDF
- Process Models
- Spellchecker
- Touch
- View Source
- Web Notifications
- WebGL
- WebRTC

## Audio and Video Codecs

Qt WebEngine supports the MPEG-4 Part 14 (MP4) file format only if the required proprietary audio and video codecs, such as H.264 and MPEG layer-3 (MP3), have been enabled. Proprietary codecs can be enabled by passing the following option to the `configure` tool when configuring Qt:

     -webengine-proprietary-codecs

For example, the following option could be passed when configuring Qt for building it at the top level:

     configure -webengine-proprietary-codecs

For more information, see Qt Configure Options.

When using cmake to build just the Qt WebEngine module, the following command can be used to configure and build (in this example, the Qt WebEngine source code is located in `C:\qt\qtwebengine`):

     qt-configure-module C:\qt\qtwebengine -webengine-proprietary-codecs
     cmake --build . --parallel

Warning: When distributing proprietary codec libraries, you must acquire licenses for them.

FFmpeg is a cross-platform solution to record, convert, and stream audio and video. It can be configured for use with several codecs, which rises licensing issues during distribution with the codec libraries. For some codecs, open source implementations, such as OpenH264, are available.

## WebEngineDriver

With WebEngineDriver, you can automate the testing of web sites across browsers. WebEngineDriver is based on ChromeDriver and can be used the same way. For more information about ChromeDriver and its use, visit ChromeDriver user site.

WebEngineDriver has slight modifications compared to ChromeDriver to be able to connect to Qt WebEngine based browsers. It is compatible with Qt WebEngine example browsers, such as Simple Browser or Nano Browser.

The browser automation is scripted through a WebDriver client like the Selenium WebDriver. For example, WebEngineDriver can be used with the Python lanugage bindings of Selenium WebDriver:

     from selenium import webdriver
     from selenium.webdriver.chrome.service import Service

     service = Service(executable_path='QTDIR/libexec/webenginedriver')
     options = webdriver.ChromeOptions()
     options.binary_location = 'path/to/browser_binary'

     driver = webdriver.Chrome(service=service, options=options)
     driver.get("http://www.google.com/")
     driver.quit()

In this example,

- `executable_path` has to be set to the WebEngineDriver's binary path
- `QTDIR` is the directory where Qt is installed
- `options.binary_location` has to be set to the browser's binary path

Note: On Windows: `executable_path='QTDIR/bin/webenginedriver.exe'`

Before executing the script, the `QTWEBENGINE_REMOTE_DEBUGGING` environment variable has to be set. Its value is a port number what is used by both the browser and WebEngineDriver to communicate with each other.

     export QTWEBENGINE_REMOTE_DEBUGGING=12345

By executing, the script opens the specified web browser and loads the Google web site.

WebEngineDriver can be also attached to an already running browser if it was started with the remote debugging port set. `options.debugger_address` has to be set to the remote debugging address in the script:

     options.debugger_address = 'localhost:12345'

In this case, `options.binary_location` should not be set because the browser is already running. The environment variable `QTWEBENGINE_REMOTE_DEBUGGING` is not used by the WebEngineDriver if `options.debugger_address` is set.

Note: WebEngineDriver must be built with the same version of Chromium as Qt WebEngine is using.

## Chromium DevTools

The Chromium DevTools provide the ability to inspect and debug layout and performance issues of any web content.

This feature can be tested by launching a Qt WebEngine application with the command line option `--remote-debugging-port=[your-port]` or by setting the environment variable `QTWEBENGINE_REMOTE_DEBUGGING` and then using a Chromium based browser (such as Simple Browser or Nano Browser) to connect to `http://localhost:[your-port]`.

Note: Any WebEngine command line options should be specified after the `--webEngineArgs` option, which is used to separate the user's application specific options from the WebEngine's ones.

     --webEngineArgs --remote-debugging-port=5000

To avoid WebSocket errors during remote debugging, add an additional command-line argument `--remote-allow-origins=<origin>[,<origin>, ...]`, where `<origin>` refers to the request origin. Use `--remote-allow-origins=*` to allow connections from all origins. If nothing is specified, Qt WebEngine will add `--remote-allow-origins=*` to command-line arguments when remote-debugging is enabled, thereby allowing requests from all origins.

The Chromium DevTools page can also be shown within the application. To set this up, you can call either QWebEnginePage::setInspectedPage() to the page to be inspected, which implicitly loads the DevTools into the `this` page, or QWebEnginePage::setDevToolsPage() to let the `this` page be inspected.

The respective QML properties are WebEngineView.devToolsView and WebEngineView.inspectedView.

For more information, see Qt WebEngine Debugging and Profiling.

## Client Certificates

Some web servers, in particular many intranet sites, require the client to authenticate itself with a certificate, called a client certificate. Qt WebEngine will read the client certificates installed in the system settings in macOS and Windows, and on Linux those installed into the NSS database. Certificates can be installed into the NSS database using the `pk12util` tool.

By default, Qt WebEngine will not offer any client certificates to servers, as doing so uniquely identifies the user and might violate privacy expectations.

To activate support for client certificates, an application needs to listen to the QWebEnginePage::selectClientCertificate or WebEngineView.selectClientCertificate signals and select one of the offered certificates. For applications that can navigate to untrusted web sites, it is recommended to always give the user a choice before uniquely identifying them to a remote server.

In addition to the client certificate stored in system settings, Qt WebEngine offers also the in-memory store. The QWebEngineClientCertificateStore instance can be obtained with the QWebEngineProfile::clientCertificateStore() method. An application can use this class to add a new certificate with a QWebEngineClientCertificateStore::add() call. Note that during the `selectClientCertificate` calls, Qt WebEngine lists both system and in-memory stored clients certificates.

See also Client Certificate Example for more implementation details.

## Custom Schemes

Qt WebEngine makes it possible for the application to define its own custom URL schemes with specialized security policies and transport mechanisms.

Custom schemes can be used to implement alternative network protocols with all the usual web security policies, privileged internal schemes for displaying user interface components or debugging information, sandboxed schemes with extra restrictions, and so on.

For more information, see QWebEngineUrlScheme and QWebEngineUrlSchemeHandler.

## Drag and Drop

Qt WebEngine supports HTML5 drag and drop.

This feature can be tested by opening an HTML5 drag and drop demo, such as HTML5 Demos - Drag and Drop, HTML5 Demos - Simple Drag and Drop, or HTML5 Demos - Drag and Drop, Automatic Upload, in Simple Browser or Nano Browser.

Dragging files into the browser is not actually part of HTML5, but it is supported. It can be tested by opening HTML5 Demos - File API.

Support for this feature was added in Qt 5.7.0.

## Favicon

Qt WebEngine supports the web site URL icon, favicon. Each icon is stored in the internal database for each QWebEngineProfile and can be accessed using a QWebEnginePage::icon() call or a WebEngineView.icon property for the currently loaded content.

Moreover Qt WebEngine provides API for accessing already stored icons in the internal profile's database.

Note: The icon database is not available for off-the-record profiles.

### QML Favicon Handling

For accessing icons a `QQuickImageProvider` is registered. This provider can be accessed by a special URL where the scheme is "image:" and the host is "favicon".

     Image {
         source: "image://favicon/url"
     }

The `url` can be the URL of the favicon:

     Image {
         source: "image://favicon/https://www.qt.io/hubfs/2016_Qt_Logo/qt_logo_green_rgb_16x16.png"
     }

The `url` also can be a page URL to access its icon:

     Image {
         source: "image://favicon/https://www.qt.io/"
     }

If more than one icon is available, the Image::sourceSize property can be specified to choose the icon with the desired size. If Image::sourceSize is not specified or 0, the largest available icon will be chosen.

The image provider looks up the requested icon in the existing WebEngineView instances. First, it tries to match the currently displayed icons. If no match has been found it requests the icon from the database. Each profile has its own icon database and it is stored in the persistent storage thus the stored icons can be accessed without network connection too. The icon must be previously loaded to be stored in the database.

### C++ Favicon Handling

A user can request an icon from the previously loaded content for each QWebEngineProfile using the QWebEngineProfile::requestIconForPageURL() or QWebEngineProfile::requestIconForIconURL() calls. Note that the profile's database is stored in the persistent storage and can be accessed without a network connection.

## Fullscreen

Qt WebEngine supports viewing web content in fullscreen mode. For more information, see WebEngineSettings.fullscreenSupportEnabled, WebEngineView.fullScreenRequested, QWebEngineSettings::FullScreenSupportEnabled, and QWebEnginePage::fullScreenRequested.

This feature can be tested by playing a video from YouTube in Video Player or Nano Browser, and clicking the full screen icon to go into fullscreen mode.

Support for this feature was added in Qt 5.6.0.

## Hardware Acceleration

Qt WebEngine tries to use hardware acceleration for rendering web content whenever possible. The actual rendering is performed by Chromium, and the final image is produced by Chromium's compositor, which makes use of modern GPU APIs such as OpenGL, Vulkan, Metal, or Direct3D, depending on the platform and available drivers.

This final image is then imported by Qt WebEngine into the Qt rendering pipeline using GPU interoperability, allowing efficient sharing of GPU resources without unnecessary copies. The imported image is passed to the Qt Quick Scene Graph, which also performs hardware-accelerated rendering through the Qt Rendering Hardware Interface (RHI).

While both Qt and Chromium rely on GPU acceleration, they may not necessarily use the same graphics API. In practice, Qt WebEngine attempts to align Chromium’s GPU backend with the one used by Qt when possible, defaulting to Qt’s chosen backend configuration to ensure compatibility and optimal performance, though it is possible to manually override these defaults if needed.

When hardware acceleration is not available or fails, Qt WebEngine automatically tries to fall back to software rendering.

### Force use of software rendering

The automatic fallback to software rendering is not always possible, and Qt WebEngine may fail to properly display web content or may exit with an error message. In such cases, it maybe necessary to explicitly disable hardware acceleration and use software rendering instead.

There are multiple ways to force software rendering:

- Disable hardware acceleration in Chromium:

       export QTWEBENGINE_CHROMIUM_FLAGS=--disable-gpu

- Disable hardware acceleration in Qt Quick Scene Graph:

       export QT_QUICK_BACKEND=software

### Changing the graphics API backend in Qt

There are two ways to choose the graphics API backend:

- Set `QSG_RHI_BACKEND` environment variable before launching application.
- Call QQuickWindow::setGraphicsApi() in combination with QSGRendererInterface::GraphicsApi before constructing the first QQuickWindow.

For more details, see Rendering via the Qt Rendering Hardware Interface.

### Changing the graphics API backend in Chromium

Changing Chromium’s graphics API backend is generally not recommended, as it may cause compatibility issues or inconsistent rendering behavior. Whenever possible, prefer using the `QSG_RHI_BACKEND` environment variable instead. However, it may be necessary in some cases for debugging or as a temporary workaround for driver-specific problems.

To override Chromium's backend, set the `QTWEBENGINE_CHROMIUM_FLAGS` environment variable to pass the corresponding Chromium command line flags, such as `--use-gl=` or `--use-angle=`.

In Qt WebEngine, Chromium currently uses the ANGLE backend by default on all platforms where hardware acceleration is supported. ANGLE is a cross-platform graphics abstraction layer in Chromium which hides the underlying native graphics backend.

The default configuration Qt WebEngine uses is this:

     export QTWEBENGINE_CHROMIUM_FLAGS="--use-gl=angle --use-angle=default"

If ANGLE crashes under a specific configuration, it can be completely disabled while still using Vulkan for hardware-accelerated rendering:

     export QTWEBENGINE_CHROMIUM_FLAGS="--use-gl=stub --enable-features=Vulkan --use-vulkan=native"

Note: Certain features such as WebGL may not work with a custom configuration like this.

Alternatively, the following configuration uses Vulkan for rendering while keeping ANGLE enabled for WebGL support:

     export QTWEBENGINE_CHROMIUM_FLAGS="--use-gl=angle --enable-features=Vulkan --use-vulkan=native"

For more details about the corresponding Chromium command line flags, see Chromium's source code: //ui/gl/gl_switches.cc

### NVIDIA on Linux

On Linux systems with an NVIDIA GPU, Chromium is forced to use Vulkan for rendering.

Qt WebEngine uses GBM buffer objects to import textures from Chromium into Qt's graphics pipeline. However, NVIDIA drivers currently do not support allocating these buffer objects. As a workaround, Qt WebEngine forces Chromium to render with Vulkan and imports the textures using Vulkan interoperability.

Note: Qt itself is not forced to use Vulkan. Chromium uses the `--use-gl=angle --enable-features=Vulkan --use-vulkan=native` configuration.

### Enable logging and troubleshooting

When a rendering issue occurs, it is important to know the failing configuration and the current state of hardware acceleration in order to investigate and report the problem effectively.

The easiest way to check this information is to load the `chrome://gpu` internal page and analyze its content. However, this page may not always be readable or available during a rendering issue.

Qt WebEngine provides logging categories that can be enabled to dump detailed graphics information:

- `qt.webenginecontext` logs how Qt WebEngine was initialized, the detected GPU, and the graphics configuration.
- `qt.webengine.compositor` logs the configuration used by Chromium and the steps Qt WebEngine takes to import textures into Qt's graphics pipeline.

To enable these logs, set the `QT_LOGGING_RULES` environment variable, for example:

     export QT_LOGGING_RULES="qt.webenginecontext=true;qt.webengine.compositor=true"

Note: If the `QSG RHI Device` used by Qt and the `GL Renderer` used by Chromium differ, it indicates that Qt and Chromium are using different GPUs in a multi-GPU system, which is currently not supported.

This is an example GPU log from `qt.webenginecontext`:

     Chromium GL Backend: angle
     Chromium ANGLE Backend: default
     Chromium Vulkan Backend: disabled

     QSG RHI Backend: OpenGL
     QSG RHI Backend Supported: yes
     QSG RHI Device: AMD AMD Radeon Graphics (radeonsi, raphael_mendocino, LLVM 20.1.8, DRM 3.61, 6.12.41-gentoo-x86_64) 4.6 (Compatibility Profile) Mesa 25.1.9
     QSG RHI GPU Vendor: AMD

The first block presents the Chromium configuration:

- `Chromium GL Backend` shows the value of the `--use-gl=` setting.
- `Chromium ANGLE Backend` shows the value of the `--use-angle=` setting.
- `Chromium Vulkan Backend` shows the value of the `--use-vulkan=` setting.

The second block presents the Qt configuration:

- `QSG RHI Backend` shows the underlying native graphics API.
- `QSG RHI Backend Supported` indicates whether this graphics API is supported by Qt WebEngine.
- `QSG RHI Device` shows metadata for the graphics device used by the RHI.
- `QSG RHI Vendor` shows the vendor of the graphics device used by the RHI.

This is an example ANGLE log from `qt.webengine.compositor` for the same GPU:

     qt.webengine.compositor: ANGLE_OPENGL display is initialized:
     GL Renderer: ANGLE (AMD, AMD Radeon Graphics (radeonsi raphael_mendocino LLVM 20.1.8), OpenGL 4.6 (Core Profile) Mesa 25.1.9)
     2 GPU(s) detected:
       Nvidia, device id: 0x1d01, driver: Mesa 25.1.9, system device id: 0x0, preference: None, active: no
       AMD, device id: 0x164e, driver: Mesa 25.1.9, system device id: 0x0, preference: None, active: yes
     NVIDIA Optimus: disabled
     AMD Switchable: disabled

The log entries above indicates:

- `ANGLE_OPENGL display is initialized` confirms that ANGLE was successfully initialized with the specified display type.
- `GL Renderer` shows metadata for the graphics device used by ANGLE (expected to match the `QSG RHI Device`).
- `2 GPU(s) detected` lists the GPUs detected by ANGLE.
- `NVIDIA Optimus` and `AMD Switchable` indicate whether ANGLE supports GPU switching at runtime (currently not supported).

## HTML5 DRM

Qt WebEngine supports displaying DRM-protected videos if the Widevine CDM plugin has been installed. The plugin comes only in a binary format, so it can hide DRM decryption implementation details. You can obtain it from a third party, or from a Google Chrome installation.

Note: The Widevine plugin is not shipped with Qt WebEngine.

On startup, Qt WebEngine looks for the Widevine CDM plugin in several well-known locations, like the default Google Chrome installation directory, or Linux distro-specific paths. You can also pass the plugin location with `QTWEBENGINE_CHROMIUM_FLAGS` using `widevine-path`.

On Windows:

     set QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="C:/some path/widevinecdm.dll"

On Linux:

     export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.so"

On macOS:

     export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.dylib"

The video format most commonly used by DRM services, H.264, requires proprietary audio and video codecs. For more information about enabling the codecs, see Audio and Video Codecs.

You can test this feature by playing a video from castLabs or Bitmovin Player in the Simple Browser or Nano Browser example projects.

Support for this feature was added in Qt 5.7.0.

## HTML5 Geolocation

Qt WebEngine supports JavaScript Geolocation API with Qt Positioning as a backend. HTML5 geolocation is disabled by default. To explicitly allow it, the application needs to listen to QWebEnginePage::permissionRequested. When a permission request with a type of QWebEnginePermission::PermissionType::Geolocation is received, you can call QWebEnginePermission::grant() on the received object to grant the required permission.

If Qt WebEngine was built with Qt Positioning support then this feature can be tested by using Maps and allowing it to find the current position of the user.

Note: On Windows 11, enable settings to grant the maps example access to Windows location services. In the Settings App under Privacy & Security > Location, enable Location services, Let apps access your location and Let desktop apps access your location.

See Qt Positioning for a possible backend setup like the GPS or IP based positioning.

Support for this feature was added in Qt 5.5.0.

## HTML5 Permissions

Qt WebEngine has support for several types of web feature permissions via the QWebEnginePermission API. Permissions can be granted (or denied) to a web domain whenever a page requests potentially sensitive user information, like access to the users' camera or geolocation.

Application developers can choose whether to ask the end user for permission or automatically make the decision for them. Moreover, they can preemptively grant or deny certain permissions, in cases where a known domain is expected to request them.

The QWebEngineProfile object stores all permissions that have been granted or denied to individual domains. Unless the current profile is off-the-record, those permissions are stored to disk and recalled the next time an application is opened. However, this behavior can be modified, and developers can choose to only store permissions until application exit, or even to make permission requests trigger every time a website asks for them.

The full list of currently supported web permissions can be found in the QWebEnginePermission documentation.

Note: Web permissions are different from application permissions, which are governed by the QPermissions API. Web permissions are granted to individual web domains, and not to the full application. However, the two APIs are not mutually exclusive. For example, access to the user's camera and microphone may require granting permission through both APIs.

## Frames

Using the QWebEngineFrame API, developers can inspect and interact with individual `<iframe>` elements within a web page. This can be used to inject JavaScript, or to print only the contents of the frame, ignoring the page it's embedded in. Frames can also be accessed recursively, for cases where frames exist inside other frames.

## HTML5 WebSockets

Qt WebEngine supports the WebSocket JavaScript API to communicate with WebSocket servers using the `ws://` or `wss://` protocols. Moreover, integration with Qt WebChannel and Qt WebSockets enables communication between JavaScript and the native side of the application.

The Qt WebChannel module has a great example for a chat server and its web based chat client. The client works out of the box in the example browsers of Qt WebEngine (such as Simple Browser or Nano Browser).

## HTTP/2 Protocol

Qt WebEngine supports the Chromium implementation of the HTTP/2 protocol.

This feature can be tested by opening an HTTP/2 demo, such as the Akamai HTTP/2 Demo, in Simple Browser or Nano Browser.

## Local Storage

Qt WebEngine supports saving key-value pairs in a `Local Storage` with no expiration date. This is a part of the Web Storage API, where a user can access a `Storage` object for the given domains using the `Window.localStorage` JavaScript property. The stored data will persist even after the page or the browser application is closed.

Note that the `Local` Storage can be also disabled with a QWebEngineSettings::LocalStorageEnabled setting. Moreover, the storage path can be adjusted with a QWebEngineProfile::setPersistentStoragePath call.

     QWebEngineProfile profile("MyProfile");
     profile.settings()->setAttribute(QWebEngineSettings::LocalStorageEnabled, isEnabled);
     profile.setPersistentStoragePath("/path/to/storage");

Qt WebEngine offers also an easy way of investigating the content of the `Local Storage` with Qt WebEngine Developer Tools by visiting the Application panel and expanding the Local Storage menu.

## Native Dialogs

A web page might request dialogs for the following functions:

- Entering user credentials for HTTP and proxy authentication
- Displaying JavaScript alerts, confirmation dialogs, and prompts
- Picking colors
- Selecting files
- Displaying form validation messages

Qt WebEngine provides standard dialogs for these functions. In widget-based applications, the standard dialogs are based on QDialog, whereas in Qt Quick applications, they can be based either on Qt Quick Controls 1 or Qt Quick Controls 2 (since Qt 5.8). The latter are used only on `eglfs` platforms.

To explicitly force either dialogs based on Qt Quick Controls 1 or Qt Quick Controls 2, set the `QTWEBENGINE_DIALOG_SET` environment variable to either `QtQuickControls1` or `QtQuickControls2`.

Qt WebEngine Widgets dialogs can be customized by reimplementing the QWebEnginePage::chooseFiles(), QWebEnginePage::javaScriptAlert(), QWebEnginePage::javaScriptConfirm(), and QWebEnginePage::javaScriptPrompt() functions.

Since Qt 5.8, Qt Quick dialogs can be customized by connecting to the WebEngineView::authenticationDialogRequested(), WebEngineView::javaScriptDialogRequested(), WebEngineView::colorDialogRequested(), WebEngineView::fileDialogRequested(), and WebEngineView::formValidationMessageRequested() signals.

## PDF File Viewing

Qt WebEngine supports viewing PDF documents by navigating to them. This feature uses the Chromium extensions API and PDF viewer plugin to display the PDF documents. It can be tested in Simple Browser or Nano Browser.

Loading plugins needs to be enabled using QWebEngineSettings::PluginsEnabled or WebEngineSettings::pluginsEnabled in order to use this feature.

This feature can be turned on (default) or off via the QWebEngineSettings::PdfViewerEnabled or WebEngineSettings::pdfViewerEnabled setting.

Support for this feature was added in Qt 5.13.0.

## Page Lifecycle API

Qt WebEngine supports the Page Lifecycle API specification, a work-in-progress extension to the HTML standard for allowing user agents to reduce their resource consumption by freezing or discarding background pages. The feature is exposed both in the Widgets and QML APIs.

For an example of the QML API in use, see the WebEngine Lifecycle Example.

Support for this feature was added in Qt 5.14.0.

### Overview of Lifecycle States

Each WebEngineView item (or QWebEnginePage object) can be in one of three lifecycle states: active, frozen, or discarded. These states, like the sleep states of a CPU, control the resource usage of web views.

The active state is the normal, unrestricted state of a web view. All visible web views are always in the active state, as are all web views that have not yet finished loading. Only invisible, idle web views can be transitioned to other lifecycle states.

The frozen state is a low CPU usage state. In this state, most HTML task sources are suspended (frozen) and, as a result, most DOM event processing and JavaScript execution will also be suspended. The web view must be invisible in order to be frozen as rendering is not possible in this state.

The discarded state is an extreme resource-saving state. In this state, the browsing context of the web view will be discarded and the corresponding renderer subprocess shut down. CPU and memory usage in this state is reduced virtually to zero. On exiting this state the web page will be automatically reloaded. The process of entering and exiting the discarded state is similar to serializing the browsing history of the web view and destroying the view, then creating a new view and restoring its history.

See also WebEngineView::LifecycleState. The equivalent in the Widgets API is QWebEnginePage::LifecycleState.

### The `lifecycleState` and `recommendedState` Properties

The lifecycleState property of the WebEngineView type is a read-write property that controls the current lifecycle state of the web view. This property is designed to place as few restrictions as possible on what states can be transitioned to. For example, it is allowed to freeze a web view that is currently playing music in the background, stopping the music. In order to implement a less aggressive resource-saving strategy that avoids interrupting user-visible background activity, the recommendedState property must be used.

The recommendedState property of the WebEngineView type is a read-only property that calculates a safe limit on the lifecycleState property, taking into account the current activity of the web view. So, in the example of a web view playing music in the background, the recommended state will be `Active` since a more aggressive state would stop the music. If the application wants to avoid interrupting background activity, then it should avoid putting the web view into a more aggressively resource-saving lifecycle state than what's given by recommendedState.

See also WebEngineView::lifecycleState and WebEngineView::recommendedState. The equivalents in the Widgets API are QWebEnginePage::lifecycleState and QWebEnginePage::recommendedState.

### The DOM Extensions

The lifecycleState property is connected to the Page Lifecycle API specification, which specifies two new DOM events, `freeze` and `resume`, and adds a new `Document.wasDiscarded` boolean property. The `freeze` and `resume` events are fired when transitioning from the `Active` to the `Frozen state`, and vice-versa. The `Document.wasDiscarded` property is set to `true` when transitioning from the `Discarded` state to the `Active` state.

## Print to PDF

Qt WebEngine supports printing a web page to a PDF file. For more information, see QWebEnginePage::printToPdf() and WebEngineView.printToPdf.

This feature can be tested using Html2Pdf.

Support for this feature was added in Qt 5.7.0.

## Process Models

Qt WebEngine uses multiple OS processes to isolate web sites from each other and from the client application, improving security and robustness. The following process models, or ways to divide web sites between OS processes, are supported:

- Process per Site Instance
- Process per Site
- Single Process

### Process per Site Instance

This is the default model. Pages from separate sites are put into separate processes and separate visits to the same site are also isolated.

Two web pages are considered as belonging to the same site if they originate from the same registered domain name (for example, `wikipedia.org`) and scheme (for example, `https`). This is similar to the same-origin policy but subdomains are ignored. For example, both `https://en.wikipedia.org/` and `https://de.wikipedia.org/` would belong to the same site.

A site instance is a collection of web pages belonging to the same site. When the application explicitly loads a URL into Qt WebEngine (via QWebEnginePage::setUrl, for example), a new site instance is created for the page. However, when the user clicks same-site links on the page, the existing site instance is merely extended with more pages.

For instance, in the Simple Browser example, when a user opens two tabs and explicitly enters `https://en.wikipedia.org/` into the URL bars, both tabs will have their own separate OS processes (because explicitly entering a URL creates a new site instance). However, when the user then middle-clicks some same-site links to open more tabs, these new tabs will share the same OS process (because user interaction extends the existing site instance).

### Process per Site

Pages from separate sites are put into separate processes. Unlike Process per Site Instance, all visits to the same site will share an OS process.

The benefit of this model is reduced memory consumption, because more web pages will share processes. The drawbacks include reduced security, robustness, and responsiveness.

To enable this model, use the command-line argument `--process-per-site`. See Using Command-Line Arguments.

### Single Process

For debugging purposes only, a single process mode can be enabled using the command-line argument `--single-process`. See Using Command-Line Arguments and Qt WebEngine Debugging and Profiling.

## Spellchecker

Qt WebEngine supports integrating spellchecking support into HTML forms to enable users to submit spellchecked messages. When the user clicks on an underlined misspelled word, the default context menu displays up to four suggestions. Selecting one will replace the misspelled word.

To be able to check the spelling, the spellchecker needs dictionaries. It supports dictionaries from the Hunspell project, but they have to be compiled into a special binary format. A Hunspell dictionary consists of two files:

- A `.dic` file that is a dictionary containing words for the language
- An `.aff` file that defines the meaning of special flags in the dictionary

These two files can be converted into the `bdic` format by using the `qwebengine_convert_dict` tool that is shipped together with Qt. When the Qt WebEngine spellchecker initializes, it will try to load the `bdict` dictionaries and to check them for consistency.

For CMake, you can use the qt_add_webengine_dictionary command to convert Hunspell `.dic` files into the `.bdic` binary format. The command creates a `qtwebengine_dictionaries` target, which your project can use a dependency.

If `QTWEBENGINE_DICTIONARIES_PATH` is set, the spellchecker uses the dictionaries in the specified directory without looking anywere else. Otherwise, it uses the qtwebengine_dictionaries directory relative to the executable if it exists. If it does not exist, it will look in `QT_INSTALL_PREFIX/qtwebengine_dictionaries`.

On macOS, depending on how Qt WebEngine is configured at build time, there are two possibilities how spellchecking data is found:

- Hunspell dictionaries (default) - .bdic dictionaries are used, just like on other platforms
- Native dictionaries - the macOS spellchecking APIs are used (which means the results will depend on the installed OS dictionaries)

Thus, in the macOS Hunspell case, Qt WebEngine will look in the qtwebengine_dictionaries subdirectory located inside the application bundle `Resources` directory, and also in the `Resources` directory located inside the Qt framework bundle.

To summarize, in case of Hunspell usage, the following paths are considered:

- `QTWEBENGINE_DICTIONARIES_PATH`, if set
- QCoreApplication::applicationDirPath()/qtwebengine_dictionaries or QCoreApplication::applicationDirPath()/../Contents/Resources/qtwebengine_dictionaries (on macOS)
- [QLibraryInfo::DataPath]/qtwebengine_dictionaries or path/to/QtWebEngineCore.framework/Resources/qtwebengine_dictionaries (Qt framework bundle on macOS)

Spellchecking is disabled by default and can be enabled per profile by using the QWebEngineProfile::setSpellCheckEnabled() method in widget-based applications and the WebEngineProfile.spellCheckEnabled property in Qt Quick applications.

The current language used for spellchecking is defined per profile, and can be set using the QWebEngineProfile::setSpellCheckLanguages() method or the WebEngineProfile.spellCheckLanguages property.

This feature can be tested by building and running the Spellchecker Example.

Qt WebEngine can be compiled also without spellchecker support with the use of a `webengine-spellchecker` configure switch.

     qt-configure-module path\to\qtwebengine\sources -no-webengine-spellchecker

For more information, see Qt Configure Options.

Support for this feature was added in Qt 5.8.0.

## Touch

Qt WebEngine supports touch devices for navigating and interacting with web pages.

The touch event support in JavaScript API depends on the presence of a touch screen (meaning `ontouchstart` and related handlers will be present in the `document.window` object if a capable touch device is connected to the system).

Some websites use this API to decide whether they run on a mobile device or on desktop and base their design on it. This can cause unwanted results on touchscreen laptops or other setups that emulate a fake touch device.

Applications can set this feature explicitly with QWebEngineSettings::TouchEventsApiEnabled.

Note that touch events will still be delivered to web pages even if the API is disabled. Dispatching touch events to web pages can be prohibited by installing an event filter object using QObject::installEventFilter on the WebEngine view focus proxy object, and filtering out all touch events.

## View Source

Qt WebEngine supports viewing the HTML source of a web page.

This feature can be used from custom menus or assigned to custom events. For more information, see WebEngineView::WebAction, and QWebEnginePage::WebAction.

This feature can be tested by opening a web page in Simple Browser or Nano Browser, and then selecting `Page Source` in the context menu. The `Page Source` context menu entry opens the source view in a new tab.

For opening the source view in the current tab, URLs with view-source URI scheme are also supported. For example, you can type the following URL to the URL bar to view the HTML source of the qt.io web page:

     view-source:https://www.qt.io/

Auto-completion of incomplete URLs with view-source URI scheme makes the usage of this feature more comfortable. For example, the following incomplete URL also loads the source view of the qt.io web page:

     view-source:qt.io

Support for this feature was added in Qt 5.8.0.

## Web Notifications

Qt WebEngine supports JavaScript Web Notifications API. The application has to explicitly allow the feature by using QWebEnginePage::Notifications or WebEngineView.Notifications.

Support for this feature was added in Qt 5.13.0.

## WebGL

Qt WebEngine supports WebGL for some graphics stacks setups. A user can visit the chrome://gpu page using the QtWebEngine powered application. The Graphics Feature Status overview states if WebGL is supported for the current platform setup. A user can also check the WebGL Report.

The WebGL support is enabled by default. You can disable it with the QWebEngineSettings::WebGLEnabled setting.

## WebRTC

WebRTC provides browsers with Real-Time Communications (RTC) capabilities via simple APIs. For more information, see WebEngineView.Feature, and QWebEnginePage::Feature.

This feature can be tested by setting up a webcam or microphone and then opening `https://test.webrtc.org/` in Simple Browser or Nano Browser.

Overview ◦ Platform Notes