Foldable Posture
Detect a foldable / dual-screen device's fold state (posture) and adapt your web layout.
At a glance
The Posture Bridge tells your web app the fold state of a foldable device. When the device folds in half like a book (vertical hinge) or lies flat like a laptop (horizontal hinge), your web app can split the layout in two or move controls to match.
State (posture) | Meaning | Recommended layout |
|---|---|---|
flat | Fully open (or a regular phone / tablet) | Normal single layout |
book | Vertical hinge (left/right split, book mode) | Left/right split (list + detail) |
tabletop | Horizontal hinge (top/bottom split, laptop mode) | Top content / bottom controls |
folded | Folded (cover screen) — iOS only | Compact UI |
unknown | Cannot determine | Treat like flat |
No breaking change — active only when you use it
This feature does not change existing behavior. Regular phones/tablets and older OS versions always report flat, and it only takes effect when your web app calls the posture API. You don't need to adopt it until you have a foldable target.
Bridge API
// Query the current posture (async — replies via callback). Defaults to 'onPosture' if omitted.
window.unveilyBridge.getPosture('onPosture');
// getPosture response handler — implemented by your web app
window.onPosture = function (result) { applyPosture(result); };
// push handler the native side calls when posture changes — implemented by your web app
window.onPostureChange = function (result) { applyPosture(result); };result shape
{
"postureContractVersion": 1,
"posture": "flat", // flat | book | tabletop | folded | unknown
"isFoldable": true,
"hingeAngle": 128, // iOS: number / Android: always null
"hingeOrientation": "vertical", // vertical | horizontal | null
"orientation": "portrait", // portrait | landscape
"segments": [ { "x": 0, "y": 0, "width": 540, "height": 960 } ] // iOS only
}book= vertical hinge (left/right split) ·tabletop= horizontal hinge (top/bottom split)- Non-foldable device →
{ "isFoldable": false, "posture": "flat" }, no push
⚠️ Cross-platform handling you must follow
iOS and Android expose the split regions in different ways. You must tolerate all of the following so neither platform breaks.
Resolve split regions (segments) in fallback order
Don't assume a single source. Handle them in this order.
- Use the CSS Viewport Segments API (
env(viewport-segment-*)) if available — supported on Android (Chromium WebView) - Otherwise use
segmentsfrom the bridge result — iOS (WKWebView doesn't support the CSS API, so it provides native segments instead) - If neither is available, branch on the
postureenum
Also:
hingeAnglemay benull(Android is always null). Don't assume it's a number.foldedmay never arrive (Android can't detect the closed state — it's the iOS cover screen only). Don't hang core logic on receivingfolded.- Android may have no
segmentskey at all, and iOS has no CSS Viewport Segments API. You must tolerate both. - Ignore unknown fields/values (forward compatibility).
Call once on load (important)
Posture changes that happened before the page loaded are not delivered via push. So on load you must call getPosture() once to get the current state.
window.addEventListener('unveilyGlueReady', () => {
try { window.unveilyBridge.getPosture('onPosture'); } catch (e) {}
}, { once: true });unveilyGlueReady is the event the SDK fires once it finishes injecting the bridge glue. (Details: Navigation — Timing)
How push relates to rotation
An onPostureChange push fires whenever posture, isFoldable, or hingeOrientation changes.
- A non-folding device (
isFoldable: false) gets no push on rotation. Handle rotation with the existingwindow.onOrientationChanged/ CSS media queries /window.resize. - A foldable fires a push on rotation because
hingeOrientationchanges (same on both platforms):- Rotating while half-folded → posture also switches
book↔tabletop - Rotating while open (
flat) → posture staysflat, onlyhingeOrientationflipsvertical↔horizontal
- Rotating while half-folded → posture also switches
Re-read when you get a push
When you receive a push, re-read hingeOrientation/orientation and reflect them in your layout even if posture is unchanged.
Example
function applyPosture(result) {
const { posture, hingeOrientation } = result;
const root = document.documentElement;
switch (posture) {
case 'book': // vertical hinge → left/right split
root.dataset.layout = 'split-horizontal';
break;
case 'tabletop': // horizontal hinge → top/bottom split
root.dataset.layout = 'split-vertical';
break;
case 'folded': // iOS cover screen
root.dataset.layout = 'compact';
break;
default: // flat / unknown
root.dataset.layout = 'single';
}
}
// once on load + on every change via push
window.onPosture = applyPosture;
window.onPostureChange = applyPosture;
window.addEventListener('unveilyGlueReady', () => {
try { window.unveilyBridge.getPosture('onPosture'); } catch (e) {}
}, { once: true });Demo
You can see it in action on the "Foldable Posture" card of the SDK test page (test_bridge). On the iPhone Duo simulator / Pixel Fold emulator you can watch the values change as you fold and rotate.