Skip to main content
Unveilydocs

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)MeaningRecommended layout
flatFully open (or a regular phone / tablet)Normal single layout
bookVertical hinge (left/right split, book mode)Left/right split (list + detail)
tabletopHorizontal hinge (top/bottom split, laptop mode)Top content / bottom controls
foldedFolded (cover screen) — iOS onlyCompact UI
unknownCannot determineTreat 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.

  1. Use the CSS Viewport Segments API (env(viewport-segment-*)) if available — supported on Android (Chromium WebView)
  2. Otherwise use segments from the bridge result — iOS (WKWebView doesn't support the CSS API, so it provides native segments instead)
  3. If neither is available, branch on the posture enum

Also:

  • hingeAngle may be null (Android is always null). Don't assume it's a number.
  • folded may never arrive (Android can't detect the closed state — it's the iOS cover screen only). Don't hang core logic on receiving folded.
  • Android may have no segments key 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 existing window.onOrientationChanged / CSS media queries / window.resize.
  • A foldable fires a push on rotation because hingeOrientation changes (same on both platforms):
    • Rotating while half-folded → posture also switches book ↔ tabletop
    • Rotating while open (flat) → posture stays flat, only hingeOrientation flips vertical ↔ horizontal

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.

On this page