Glassly Miniapp SDK betaThe SDK is in beta, so its APIs may change before general availability.Developing on Mentra Live? We recommend using the Glassly Bluetooth SDK.The developer tools are available in the Glassly App under Settings → Miniapp Developer Settings.Share feedback with an in-app bug report, on Discord, or by email at [email protected].
Your miniapp UI runs in a WebView inside the Glassly App, and the host draws its own chrome on top. Two things overlap your content: the device safe-area insets (notch, status bar, rounded corners) and a floating capsule menu the host parks in the top-right. If you lay out edge-to-edge, your header sits under the notch and your top-right button sits under the capsule, where taps go to the host instead of your app. On an iPhone Duo the status bar is a vertical rail along one side instead, and the capsule sits in it (see The iPhone Duo’s status rail). useSafeArea() reads both regions so your layout can pad around them. It imports from @glassly/miniapp/react, the UI layer of the two-layer architecture.
The host injects these values before your content loads and updates them when they change, for example when an iPhone Duo folds or unfolds. The hook re-renders with the new values.

useSafeArea()

Returns an object with two fields. insets always has all four sides, defaulting to 0 when the host provides none (for example, a browser preview): capsuleMenu is the rect of the floating control in the top-right. Use it to keep interactive elements out from under the menu, since taps there reach the host.
Coordinates are in CSS pixels. Always handle capsuleMenu === null so your layout still works outside the Glassly App, on hosts that don’t draw a menu, and on an iPhone Duo.

The iPhone Duo’s status rail

On an iPhone Duo the camera and status bar sit in an 84px vertical rail along the right edge, or along the left edge when the Glassly App is the left window of Split View, and the host stacks the capsule menu in it. The rail reaches your miniapp as a side inset (insets.right or insets.left) and the top inset is often 0. Let backgrounds run under the rail and stop content at it: on the rail’s side, use the inset in place of your usual page padding rather than adding the two.
Plain HTML pages can do the same in CSS. The host sets --glassly-safe-top, --glassly-safe-right, --glassly-safe-bottom and --glassly-safe-left on the root element and updates them on a fold, then dispatches glassly:safe-area-change on window with window.Glassly already updated.

Back buttons in the rail

In the rail, the Glassly App puts a screen’s back button under the capsule menu, the way iOS stacks its own toolbar buttons there. useRailBackButton(onBack) gives your page’s back action to the host, which draws that button on whichever side the rail is. It returns true while the host shows the button, so hide your own then.
Pass null when the page has nothing to go back to. If several mounted components pass a handler, the one mounted last wins. Without a rail, and on hosts older than the hook, it returns false and your button stays. <MiniappHeader onBack> does all of this for you. Plain HTML pages call window.glassly.setBackAction(handler), or pass null to take it back, and hide their own button while window.Glassly.capsuleMenu.placement is "rail". Older hosts don’t have setBackAction, so check for it first.

useCapsuleHeaderStyle()

When you want your own header markup but want the capsule alignment done for you, useCapsuleHeaderStyle() returns a CSSProperties object you spread onto your header element. It positions the row vertically centered on the capsule menu and reserves room on the right so your content doesn’t slide under it.
It accepts an options object. All four are optional and have fallbacks used when the host doesn’t render a capsule menu, or draws it in the iPhone Duo’s status rail. The returned style sets display: flex with justifyContent: "space-between", so a left child and a right child split to opposite ends of the row.

<MiniappHeader>

For a stock header, <MiniappHeader> renders the aligned row for you. It has three slots (left, title, right) and respects the safe area and capsule menu the same way. It also accepts every useCapsuleHeaderStyle() option as a prop.
<MiniappHeader> also forwards leftPadding, rightGap, fallbackHeight, and fallbackMarginTop through to the underlying useCapsuleHeaderStyle(). The component ships only the layout, so use className or style for colors and fonts.

Next steps

React webviews

The UI layer overview and its hooks.

Two-layer architecture

How the UI and background layers split and talk.