Guide · Open source
How to use WebViewJavascriptBridge: setup, handlers and calls
Updated · written with AI from the project's own documentation and checked against our catalogue data
WebViewJavascriptBridge is an Objective-C library for iOS and OS X apps that lets native code and JavaScript inside a web view send messages to each other. This guide shows how to install it with CocoaPods, wire up a bridge, register handlers on both sides and make calls that return a response. By the end you will have a working two-way message setup in a native app that displays web content.
WebViewJavascriptBridgemarcuswestin/WebViewJavascriptBridge · ★ 14.3k · MIT Install options & downloads Quick start
- 1Install the pod. Add pod 'WebViewJavascriptBridge', '~> 6.0' to your podfile and run pod install.
- 2Import and create the bridge. Import WebViewJavascriptBridge.h and create the bridge with bridgeForWebView, passing your web view.
- 3Register an Obj-C handler. Use registerHandler to name a block the JavaScript can call.
- 4Add the JavaScript setup snippet. Paste setupWebViewJavascriptBridge into your JavaScript.
- 5Register a JS handler and make a call. Inside the setup callback, register a JS handler and call an Obj-C handler with callHandler.
Check what you need before you start
The library is aimed at iOS and OS X developers who embed web content in a native app. The README lists Xcode and CocoaPods as prerequisites for the CocoaPods install route.
Setup requires editing both native Objective-C code and JavaScript, so some Xcode experience is expected.
- Xcode
- CocoaPods, with a podfile in your project
- A WKWebView, UIWebView (iOS) or WebView (OSX) to bridge
Install WebViewJavascriptBridge with CocoaPods
Add the pod to your podfile, then run pod install to install it.
pod 'WebViewJavascriptBridge', '~> 6.0'
pod installCreate the bridge for your web view
Import the header file and declare a property to hold the bridge. Then create the bridge by passing it your web view. The README says the bridge can be built from a WKWebView, a UIWebView (iOS) or a WebView (OSX).
#import "WebViewJavascriptBridge.h"
@property WebViewJavascriptBridge* bridge;
self.bridge = [WebViewJavascriptBridge bridgeForWebView:webView];Register handlers and call JavaScript from Obj-C
A handler is a named block. Register one with registerHandler, and the JavaScript side can call it by that name. To call a JavaScript handler, use callHandler. Pass a responseCallback block if you want the JavaScript handler to send a value back.
- registerHandler:handler: names a handler the JavaScript can call.
- callHandler:data: sends a message with no reply expected.
- callHandler:data:responseCallback: sends a message and receives the JavaScript response.
[self.bridge registerHandler:@"ObjC Echo" handler:^(id data, WVJBResponseCallback responseCallback) {
NSLog(@"ObjC Echo called with: %@", data);
responseCallback(data);
}];
[self.bridge callHandler:@"JS Echo" data:nil responseCallback:^(id responseData) {
NSLog(@"ObjC received response: %@", responseData);
}];Add the JavaScript setup snippet
Copy the setupWebViewJavascriptBridge function from the README into your JavaScript. It gives your page access to the bridge object before you use it. The README notes that projects upgrading from v5.0.x to 6.0.x need to update this snippet.
function setupWebViewJavascriptBridge(callback) {
if (window.WebViewJavascriptBridge) { return callback(WebViewJavascriptBridge); }
if (window.WVJBCallbacks) { return window.WVJBCallbacks.push(callback); }
window.WVJBCallbacks = [callback];
var WVJBIframe = document.createElement('iframe');
WVJBIframe.style.display = 'none';
WVJBIframe.src = 'https://__bridge_loaded__';
document.documentElement.appendChild(WVJBIframe);
setTimeout(function() { document.documentElement.removeChild(WVJBIframe) }, 0)
}Register handlers and call Obj-C from JavaScript
Inside the setup callback, register JavaScript handlers and call the Obj-C handlers you defined. The README places your app initialisation inside this callback.
setupWebViewJavascriptBridge(function(bridge) {
/* Initialize your app here */
bridge.registerHandler('JS Echo', function(data, responseCallback) {
console.log("JS Echo called with:", data)
responseCallback(data)
})
bridge.callHandler('ObjC Echo', {'key':'value'}, function responseCallback(responseData) {
console.log("JS received response:", responseData)
})
})Handle non-ARC projects and the alert-box timeout
The library relies on ARC. If your project does not use ARC, the README says to add the -fobjc-arc compiler flag to each of the library's .m files under Build Phases, Compile Sources.
The README also lists disableJavscriptAlertBoxSafetyTimeout, which speeds up message passing by turning off a setTimeout safety check. It is marked UNSAFE: if the bridged JavaScript calls alert, confirm or prompt, the app will hang. Use it only if you never call those functions.
What people use it for
- Calling a native function, such as reading the screen height, from a JavaScript page in an app (the README's getScreenHeight example).
- Sending log messages from JavaScript to NSLog in Obj-C.
- Asking the web page for its current URL from native code, using a response callback.
- Showing a native alert from a JavaScript call with callHandler.
Frequently asked questions
How do I install WebViewJavascriptBridge?
The README installs it with CocoaPods. Add pod 'WebViewJavascriptBridge', '~> 6.0' to your podfile and run pod install. A manual install is also described: drag the WebViewJavascriptBridge folder into your project.
What do I need to use WebViewJavascriptBridge?
The listed prerequisites are Xcode and CocoaPods. You also need a WKWebView, UIWebView (iOS) or WebView (OSX) to attach the bridge to, and you must edit both Objective-C and JavaScript code.
Is WebViewJavascriptBridge free to use?
The project is licensed under MIT, as listed in the repository summary. Check the license file in the repository for the full terms before using it in a commercial app.
Does WebViewJavascriptBridge work with WKWebView?
Yes. The README says the bridge is for sending messages between Obj-C and JavaScript in WKWebViews, UIWebViews and WebViews, and the bridge can be created from a WKWebView.
Why does my app hang when I use the bridge?
A likely cause is the disableJavscriptAlertBoxSafetyTimeout option. The README warns that if you disable the safety check and the bridged JavaScript calls alert, confirm or prompt, the app will hang. Leave the safety check on if you use those functions.
What are alternatives to WebViewJavascriptBridge and how do they compare?
The repository lists WKWebViewJavascriptBridge, Cordova and React Native as comparable projects. WebViewJavascriptBridge is narrower: it only links native code and JavaScript in iOS and OS X web views, while the other options are broader frameworks. Check each project's own docs to compare features.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
WebViewJavascriptBridge suits iOS or OS X developers who already show web content in a native app and need a simple message bridge between Obj-C and JavaScript. If your app is fully web-based, or you need Android or other non-Apple platforms, the description does not cover those cases, so look at options like Cordova or React Native instead.
Install options & downloads