A tiny cross-platform webview library for C/C++ to build modern cross-platform GUIs.
The goal of the project is to create a common HTML5 UI abstraction layer for the most widely used platforms.
It supports two-way JavaScript bindings (to call JavaScript from C/C++ and to call C/C++ from JavaScript).
Note
Language binding for Go
. Versions <= 0.1.1 are available in this repository.
Platform Support
PlatformTechnologiesLinux
,
macOSCocoa,
Windows
,
Documentation
The most up-to-date documentation is right in the source code. Improving the documentation is a continuous effort and you are more than welcome to contribute.
Prerequisites
Your compiler must support minimum C++11.
This project uses CMake and Ninja, and while recommended for your convenience, these tools aren't required for using the library.
Linux and BSD
The
and
libraries are required for development and distribution. You need to check your package repositories regarding which packages to install.
Packages
Debian: WebKitGTK 6.0, GTK 4: Development: apt install libgtk-4-dev libwebkitgtk-6.0-dev
Production: apt install libgtk-4-1 libwebkitgtk-6.0-4
WebKitGTK 4.1, GTK 3, libsoup 3: Development: apt install libgtk-3-dev libwebkit2gtk-4.1-dev
Production: apt install libgtk-3-0 libwebkit2gtk-4.1-0
WebKitGTK 4.0, GTK 3, libsoup 2: Development: apt install libgtk-3-dev libwebkit2gtk-4.0-dev
Production: apt install libgtk-3-0 libwebkit2gtk-4.0-37
Fedora: WebKitGTK 6.0, GTK 4: Development: dnf install gtk4-devel webkitgtk6.0-devel
Production: dnf install gtk4 webkitgtk6.0
WebKitGTK 4.1, GTK 3, libsoup 3: Development: dnf install gtk3-devel webkit2gtk4.1-devel
Production: dnf install gtk3 webkit2gtk4.1
WebKitGTK 4.0, GTK 3, libsoup 2: Development: dnf install gtk3-devel webkit2gtk4.0-devel
Production: dnf install gtk3 webkit2gtk4.0
FreeBSD: GTK 4: pkg install webkit2-gtk4
GTK 3: pkg install webkit2-gtk3
Library Dependencies
Linux: Use pkg-config with --cflags and --libs to get the compiler/linker options for one of these sets of modules: gtk4 webkitgtk-6.0
gtk+-3.0 webkit2gtk-4.1
gtk+-3.0 webkit2gtk-4.0
Link libraries: dl
macOS: Link frameworks: WebKit
Link libraries: dl
Windows:
.
Windows libraries: advapi32 ole32 shell32 shlwapi user32 version
BSD
Execution on BSD-based systems may require adding the wxallowed option (see
) to your fstab to bypass
memory protection for your executable. Please see if it works without disabling this security feature first.
Windows
Your compiler must support C++14 and we recommend to pair it with an up-to-date Windows 10 SDK.
For Visual C++ we recommend Visual Studio 2022 or later. There are some
requirements when using MinGW-w64
.
Developers and end-users must have the
installed on their system for any version of Windows before Windows 11.
Getting Started
If you are a developer of this project then please go to the
.
You will have a working app, but you are encouraged to explore the
.
Create the following files in a new directory:
.gitignore:
# Build artifacts /build C++ Example
CMakeLists.txt:
cmake_minimum_required(VERSION3.16) project(example LANGUAGESCXX) set(CMAKE_RUNTIME_OUTPUT_DIRECTORY"${CMAKE_BINARY_DIR}/bin") set(CMAKE_LIBRARY_OUTPUT_DIRECTORY"${CMAKE_BINARY_DIR}/lib") set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY"${CMAKE_BINARY_DIR}/lib") include(FetchContent) FetchContent_Declare( webview GIT_REPOSITORY https://github.com/webview/webview GIT_TAG 0.12.0) FetchContent_MakeAvailable(webview) add_executable(exampleWIN32) target_sources(examplePRIVATEmain.cc) target_link_libraries(examplePRIVATEwebview::core)main.cc:
#include"webview/webview.h" #include<iostream> #ifdef _WIN32 intWINAPIWinMain(HINSTANCE/*hInst*/, HINSTANCE/*hPrevInst*/, LPSTR/*lpCmdLine*/, int/*nCmdShow*/) { #elseintmain() { #endif try { webview::webview w(false, nullptr); w.set_title("Basic Example"); w.set_size(480, 320, WEBVIEW_HINT_NONE); w.set_html("Thanks for using webview!"); w.run(); } catch (const webview::exception &e) { std::cerr << e.what() << '\n'; return1; } return0; }C Example
CMakeLists.txt:
cmake_minimum_required(VERSION3.16) project(example LANGUAGESCCXX) set(CMAKE_RUNTIME_OUTPUT_DIRECTORY"${CMAKE_BINARY_DIR}/bin") set(CMAKE_LIBRARY_OUTPUT_DIRECTORY"${CMAKE_BINARY_DIR}/lib") set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY"${CMAKE_BINARY_DIR}/lib") include(FetchContent) FetchContent_Declare( webview GIT_REPOSITORY https://github.com/webview/webview GIT_TAG 0.12.0) FetchContent_MakeAvailable(webview) add_executable(exampleWIN32) target_sources(examplePRIVATEmain.c) target_link_libraries(examplePRIVATEwebview::core_static)main.c:
#include"webview/webview.h" #include<stddef.h> #ifdef _WIN32 #include<windows.h> #endif #ifdef _WIN32 intWINAPIWinMain(HINSTANCE hInst, HINSTANCE hPrevInst, LPSTR lpCmdLine, int nCmdShow) { (void)hInst; (void)hPrevInst; (void)lpCmdLine; (void)nCmdShow; #elseintmain(void) { #endif webview_t w = webview_create(0, NULL); webview_set_title(w, "Basic Example"); webview_set_size(w, 480, 320, WEBVIEW_HINT_NONE); webview_set_html(w, "Thanks for using webview!"); webview_run(w); webview_destroy(w); return0; }Building the Example
Build the project:
cmake -G Ninja -B build -S . -D CMAKE_BUILD_TYPE=Release cmake --build buildFind the executable in the build/bin directory.
Building Amalgamated Library
An amalgamated library can be built when building the project using CMake, or the amalgamate.py script can be invoked directly.
The latter is described below.
python3 scripts/amalgamate/amalgamate.py --base core --search include --output webview_amalgamation.h srcSee python3 scripts/amalgamate/amalgamate.py --help for script usage.
Non-CMake Usage
Here's an example for invoking GCC/Clang-like compilers directly. Use the main.cc file from the previous example.
Place either the amalgamated webview.h header or all of the individual files into libs/webview, and WebView2.h from
into libs.
Build the project on your chosen platform.
macOSc++ main.cc -O2 --std=c++11 -Ilibs -framework WebKit -ldl -o exampleLinuxc++ main.cc -O2 --std=c++11 -Ilibs $(pkg-config --cflags --libs gtk+-3.0 webkit2gtk-4.1) -ldl -o exampleWindowsc++ main.cc -O2 --std=c++14 -static -mwindows -Ilibs -ladvapi32 -lole32 -lshell32 -lshlwapi -luser32 -lversion -o exampleCustomization
CMake Targets
The following CMake targets are available:
NameDescriptionwebview::coreHeaders for C++.webview::core_sharedShared library for C.webview::core_staticStatic library for C.Special targets for on-demand checks and related tasks:
NameDescriptionwebview_format_checkCheck files with clang-format.webview_reformatReformat files with clang-format.CMake Options
The following boolean options can be used when building the webview project standalone or when building it as part of your project (e.g. with FetchContent).
OptionDescriptionWEBVIEW_BUILDEnable buildingWEBVIEW_BUILD_AMALGAMATIONBuild amalgamated libraryWEBVIEW_BUILD_DOCSBuild documentationWEBVIEW_BUILD_EXAMPLESBuild examplesWEBVIEW_BUILD_SHARED_LIBRARYBuild shared librariesWEBVIEW_BUILD_STATIC_LIBRARYBuild static librariesWEBVIEW_BUILD_TESTSBuild testsWEBVIEW_ENABLE_CHECKSEnable checksWEBVIEW_ENABLE_CLANG_FORMATEnable clang-formatWEBVIEW_ENABLE_CLANG_TIDYEnable clang-tidyWEBVIEW_ENABLE_PACKAGINGEnable packagingWEBVIEW_INSTALL_DOCSInstall documentationWEBVIEW_INSTALL_TARGETSInstall targetsWEBVIEW_IS_CIInitialized by the CI environment variableWEBVIEW_PACKAGE_AMALGAMATIONPackage amalgamated libraryWEBVIEW_PACKAGE_DOCSPackage documentationWEBVIEW_PACKAGE_HEADERSPackage headersWEBVIEW_PACKAGE_LIBPackage compiled librariesWEBVIEW_STRICT_CHECKSMake checks strictWEBVIEW_STRICT_CLANG_FORMATMake clang-format check strictWEBVIEW_STRICT_CLANG_TIDYMake clang-tidy check strictWEBVIEW_USE_COMPAT_MINGWUse compatibility helper for MinGWWEBVIEW_USE_STATIC_MSVC_RUNTIMEUse static runtime library (MSVC)Note
Checks are enabled by default, but aren't enforced by default for local development (controlled by the WEBVIEW_IS_CI option).
Non-boolean options:
OptionDescriptionWEBVIEW_CLANG_FORMAT_EXEPath of the clang-format executable.WEBVIEW_CLANG_TIDY_EXEPath of the clang-tidy executable.Package Consumer Options
These options can be used when when using the webview CMake package.
Linux-specific Options
OptionDescriptionWEBVIEW_WEBKITGTK_APIWebKitGTK API to interface with, e.g. 6.0, 4.1 (recommended) or 4.0. This will also automatically decide the GTK version. Uses the latest recommended API by default if available, or the latest known and available API. Note that there can be major differences between API versions that can affect feature availability. See webview API documentation for details on feature availability.Windows-specific Options
OptionDescriptionWEBVIEW_MSWEBVIEW2_VERSIONMS WebView2 version, e.g. 1.0.1150.38.WEBVIEW_USE_BUILTIN_MSWEBVIEW2Use built-in MS WebView2.Compile-time Options
These options can be specified as preprocessor macros to modify the build, but are not needed when using CMake.
C API Linkage
NameDescriptionWEBVIEW_APIControls C API linkage, symbol visibility and whether it's a shared library. By default this is inline for C++ and extern for C.WEBVIEW_BUILD_SHAREDModifies WEBVIEW_API for building a shared library.WEBVIEW_SHAREDModifies WEBVIEW_API for using a shared library.WEBVIEW_STATICModifies WEBVIEW_API for building or using a static library.Backend Selection
NameDescriptionWEBVIEW_GTKCompile the GTK/WebKitGTK backend.WEBVIEW_COCOACompile the Cocoa/WebKit backend.WEBVIEW_EDGECompile the Win32/WebView2 backend.Windows-specific Options
OptionDescriptionWEBVIEW_MSWEBVIEW2_BUILTIN_IMPLEnables (1) or disables (0) the built-in implementation of the WebView2 loader. Enabling this avoids the need for WebView2Loader.dll but if the DLL is present then the DLL takes priority. This option is enabled by default.WEBVIEW_MSWEBVIEW2_EXPLICIT_LINKEnables (1) or disables (0) explicit linking of WebView2Loader.dll. Enabling this avoids the need for import libraries (*.lib). This option is enabled by default if WEBVIEW_MSWEBVIEW2_BUILTIN_IMPL is enabled.MinGW-w64 Requirements
In order to build this library using MinGW-w64 on Windows then it must support C++14 and have an up-to-date Windows SDK.
Distributions that are known to be compatible:
MS WebView2 Loader
Linking the WebView2 loader part of the Microsoft WebView2 SDK is not a hard requirement when using our webview library, and neither is distributing WebView2Loader.dll with your app.
If, however, WebView2Loader.dll is loadable at runtime, e.g. from the executable's directory, then it will be used; otherwise our minimalistic implementation will be used instead.
Should you wish to use the official loader then remember to distribute it along with your app unless you link it statically. Linking it statically is possible with Visual C++ but not MinGW-w64.
Here are some of the noteworthy ways our implementation of the loader differs from the official implementation:
Does not support configuring WebView2 using environment variables such as WEBVIEW2_BROWSER_EXECUTABLE_FOLDER.
Microsoft Edge Insider (preview) channels are not supported.
can be used to change how the library integrates the WebView2 loader.
Thread Safety
Since library functions generally do not have thread safety guarantees, webview_dispatch() (C) / webview::dispatch() (C++) can be used to schedule code to execute on the main/GUI thread and thereby make that execution safe in multi-threaded applications.
webview_return() (C) / webview::resolve() (C++) uses *dispatch() internally and is therefore safe to call from another thread.
The main/GUI thread should be the thread that calls webview_run() (C) / webview::run() (C++).
Development
This project uses the CMake build system.
Development Dependencies
In addition to the dependencies mentioned earlier in this document for developing with the webview library, the following are used during development of the webview library.
Amalgamation: Python >= 3.9
Checks: clang-format
clang-tidy
Documentation: Doxygen
Graphvis
Building
cmake -G "Ninja Multi-Config" -B build -S . cmake --build build --config CONFIGReplace CONFIG with one of Debug, Release, or Profile. Use Profile to enable code coverage (GCC/Clang).
Run tests:
ctest --test-dir build --build-config CONFIGGenerate test coverage report:
gcovrFind the coverage report in build/coverage.
Packaging
Run this after building the Debug and Release configs of the project:
cd build cpack -G External -C "Debug;Release" --config CPackConfig.cmakeCross-compilation
See CMake toolchain files in the cmake/toolchains directory.
For example, this targets Windows x64 on Linux with POSIX threads:
cmake -G "Ninja Multi-Config" -B build -S . -D CMAKE_TOOLCHAIN_FILE=cmake/toolchains/x86_64-w64-mingw32.cmake -D WEBVIEW_TOOLCHAIN_EXECUTABLE_SUFFIX=-posix cmake --build build --config CONFIGLimitations
Browser Features
Since a browser engine is not a full web browser it may not support every feature you may expect from a browser. If you find that a feature does not work as expected then please consult with the browser engine's documentation and
if you think that the library should support it.
For example, the library does not attempt to support user interaction features like alert(), confirm() and prompt() and other non-essential features like console.log().
Bindings
LanguageProjectAda
Bun
C#
C3
Crystal
D
,
Deno
Go
Harbour
Haskell
Janet
Java
Kotlin
MoonBit
Nim
,
Node.js
Winterreisender/webview-nodejs
Odin
Pascal
Python
,
PHP
,
,
Ring
Ruby
Rust
Swift
V
,
Vala
Zig
,
If you wish to add bindings to the list, feel free to submit a pull request or
.
Generating Bindings
You can generate bindings for the library by yourself using the included SWIG interface (webview.i).
Here are some examples to get you started. Unix-style command lines are used for conciseness.
mkdir -p build/bindings/{python,csharp,java,ruby} swig -c++ -python -outdir build/bindings/python -o build/bindings/python/python_wrap.cpp webview.i swig -c++ -csharp -outdir build/bindings/csharp -o build/bindings/csharp/csharp_wrap.cpp webview.i swig -c++ -java -outdir build/bindings/java -o build/bindings/java/java_wrap.cpp webview.i swig -c++ -ruby -outdir build/bindings/ruby -o build/bindings/ruby/ruby_wrap.cpp webview.iLicense
Code is distributed under MIT license, feel free to use it in your proprietary projects as well.