Documentation Index
Fetch the complete documentation index at: https://mintlify.com/webviewjs/webview/llms.txt
Use this file to discover all available pages before exploring further.
WebviewJS on iOS is an experimental platform target that surfaces Tao’s WKWebView-backed iOS window on top of UIKit. Because UIKit imposes strict constraints on orientation, system-gesture edges, home indicators, and status-bar presentation, WebviewJS exposes these as both creation-time BrowserWindowOptions fields and runtime setters. This lets you tailor the host window to the exact UX your app requires without writing any Swift or Objective-C.
iOS support is experimental. APIs, binary targets, and behaviour may change without a semver-breaking release. Test thoroughly before shipping to the App Store.
iOS-Specific Window Options
All iOS-specific fields in BrowserWindowOptions are optional and map directly onto Tao’s WindowBuilderExtIOS trait:
import { IosValidOrientations } from '@webviewjs/webview';
const win = app.createBrowserWindow({
// Render at 2× regardless of the device's native scale
iosScaleFactor: 2.0,
// Allow both landscape and portrait orientations
iosValidOrientations: IosValidOrientations.LandscapeAndPortrait,
// Hide the home indicator in immersive / game-style UIs
iosPrefersHomeIndicatorHidden: true,
// Defer system swipe-from-edge gestures (bitmask: top=1, left=2, bottom=4, right=8)
iosDeferredSystemGestureEdges: 4, // defer bottom-edge swipe-up
// Hide the status bar
iosPrefersStatusBarHidden: false,
});
Option Reference
| Option | Type | Description |
|---|
iosScaleFactor | number | Content scale factor override for the UIView |
iosValidOrientations | IosValidOrientations | Which device orientations are permitted |
iosPrefersHomeIndicatorHidden | boolean | Hide the home indicator bar |
iosDeferredSystemGestureEdges | number | Bitmask of screen edges that defer system gestures |
iosPrefersStatusBarHidden | boolean | Hide the status bar |
IosValidOrientations Enum
The IosValidOrientations enum restricts which device orientations UIKit will rotate into:
import { IosValidOrientations } from '@webviewjs/webview';
// Allow any orientation
IosValidOrientations.LandscapeAndPortrait // 0 — default
// Landscape only (left and right)
IosValidOrientations.Landscape // 1
// Portrait only (upright and upside-down)
IosValidOrientations.Portrait // 2
Runtime Setters
All creation-time options can also be updated at runtime using dedicated setter methods on BrowserWindow:
Scale Factor
// Override the UIView content scale factor at runtime
win.setIosScaleFactor(3.0);
Valid Orientations
import { IosValidOrientations } from '@webviewjs/webview';
// Restrict to portrait-only after the window is created
win.setValidOrientations(IosValidOrientations.Portrait);
// Restore landscape + portrait
win.setValidOrientations(IosValidOrientations.LandscapeAndPortrait);
Home Indicator
// Hide the home indicator for an immersive full-screen experience
win.setPrefersHomeIndicatorHidden(true);
// Restore it
win.setPrefersHomeIndicatorHidden(false);
Deferred System Gesture Edges
Screen edges use a numeric bitmask — set one or combine multiple:
| Edge | Bitmask value |
|---|
| Top | 1 |
| Left | 2 |
| Bottom | 4 |
| Right | 8 |
// Defer bottom-edge swipe-up (home gesture) only
win.setPreferredScreenEdgesDeferringSystemGestures(4);
// Defer both left and right edges
win.setPreferredScreenEdgesDeferringSystemGestures(2 | 8); // 10
// Clear all deferrals
win.setPreferredScreenEdgesDeferringSystemGestures(0);
Deferring system gesture edges only delays the system gesture by requiring the user to swipe again. It does not permanently block gestures — UIKit will always allow a second swipe through.
Status Bar Visibility
// Hide the status bar for a full-bleed layout
win.setPrefersStatusBarHidden(true);
// Show it again
win.setPrefersStatusBarHidden(false);
Example: Immersive Full-Screen App
The following configuration creates a window suitable for a game or media player that occupies the full screen without system chrome:
import { Application, IosValidOrientations } from '@webviewjs/webview';
const app = new Application();
const win = app.createBrowserWindow({
iosScaleFactor: 2.0,
iosValidOrientations: IosValidOrientations.Landscape,
iosPrefersHomeIndicatorHidden: true,
iosDeferredSystemGestureEdges: 4, // defer bottom swipe
iosPrefersStatusBarHidden: true,
});
const webview = win.createWebview({ url: 'app://localhost/' });
app.run();
Combine iosPrefersStatusBarHidden: true with iosPrefersHomeIndicatorHidden: true and iosDeferredSystemGestureEdges: 15 (all edges) to get a truly edge-to-edge, gesture-safe layout on iOS.