# Safe areas & the capsule menu

> Lay out your webview UI around the host chrome: notch insets and the floating capsule menu.

Source: https://docs.glassly.ai/app-devs/core-concepts/webviews/safe-areas/

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](#the-iphone-duos-status-rail)).

`useSafeArea()` reads both regions so your layout can pad around them. It imports
from `@glassly/miniapp/react`, the [UI layer](https://docs.glassly.ai/app-devs/core-concepts/webviews/react-webviews.md)
of the [two-layer architecture](https://docs.glassly.ai/app-devs/core-concepts/two-layer-architecture.md).

```tsx
import { useSafeArea } from "@glassly/miniapp/react";

function App() {
  const { insets } = useSafeArea();

  return (
    <div
      style={{
        paddingTop: insets.top,
        paddingBottom: insets.bottom,
        paddingLeft: insets.left,
        paddingRight: insets.right,
      }}>
      <h1>My Miniapp</h1>
    </div>
  );
}
```

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.

| Field | Type | Description |
|---|---|---|
| `insets` | `MiniappSafeAreaInsets` | Pixel insets around the WebView content. Apply as padding on your root element. |
| `capsuleMenu` | `MiniappCapsuleMenuRect \| null` | Bounding rect of the host's capsule menu when it floats over your content. `null` when the host doesn't render one (e.g. older builds) or draws it in the iPhone Duo's status rail, outside your content. |

`insets` always has all four sides, defaulting to `0` when the host provides none
(for example, a browser preview):

| `insets` field | Type | Description |
|---|---|---|
| `top` | `number` | Inset from the top edge. |
| `bottom` | `number` | Inset from the bottom edge. |
| `left` | `number` | Inset from the left edge. |
| `right` | `number` | Inset from the right edge. |

`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.

| `capsuleMenu` field | Type | Description |
|---|---|---|
| `top` | `number` | Distance from the top of the viewport to the menu. |
| `right` | `number` | Distance from the right of the viewport to the menu. |
| `bottom` | `number` | Distance from the top to the menu's bottom edge. |
| `left` | `number` | Distance from the left to the menu's left edge. |
| `width` | `number` | Menu width in CSS pixels. |
| `height` | `number` | Menu height in CSS pixels. |
| `placement` | `"corner" \| "rail"` | Where the host draws the menu. Absent on older hosts. |

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.

```tsx
const { insets } = useSafeArea();

<main
  style={{
    paddingTop: insets.top,
    paddingLeft: Math.max(16, insets.left),
    paddingRight: Math.max(16, insets.right),
  }}>
```

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.

```css
body {
  padding: 16px max(16px, var(--glassly-safe-right, 0px)) 16px max(16px, var(--glassly-safe-left, 0px));
}
```

### 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.

```tsx
import { useRailBackButton } from "@glassly/miniapp/react";

function DetailHeader({ onBack }: { onBack: () => void }) {
  const backInRail = useRailBackButton(onBack);

  return (
    <header>
      {!backInRail && <button aria-label="Back" onClick={onBack}>‹</button>}
      <h1>Details</h1>
    </header>
  );
}
```

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.

```tsx
import { useCapsuleHeaderStyle } from "@glassly/miniapp/react";

function Header() {
  const style = useCapsuleHeaderStyle();

  return (
    <header style={style}>
      <h1>Hello</h1>
    </header>
  );
}
```

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.

| Option | Type | Default | Description |
|---|---|---|---|
| `leftPadding` | `number` | `20` | Extra left padding beyond the safe area. |
| `rightGap` | `number` | `16` | Space between the header content and the capsule menu. |
| `fallbackHeight` | `number` | `32` | Header height when no capsule menu is present. |
| `fallbackMarginTop` | `number` | `16` | Top margin when no capsule menu is present. |

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.

```tsx
import { MiniappHeader } from "@glassly/miniapp/react";

function App() {
  return (
    <>
      <MiniappHeader
        title="My Miniapp"
        onBack={() => history.back()}
        right={<span>Connected</span>}
      />
      {/* page content */}
    </>
  );
}
```

| Prop | Type | Description |
|---|---|---|
| `title` | `ReactNode` | A string renders as a semantic `<h1>`. Pass a node for custom markup. |
| `left` | `ReactNode` | Left slot, typically a back button or logo. Overrides `onBack` if both are set. |
| `onBack` | `() => void` | Renders a back chevron in the left slot that calls this handler. In an iPhone Duo's rail the host draws the button instead. Ignored when `left` is set. |
| `right` | `ReactNode` | Right slot, typically a badge or action buttons. Sits to the left of the capsule. |
| `className` | `string` | Applied to the header element. |
| `style` | `CSSProperties` | Inline overrides merged over the computed layout style. |
| `bottomSpacer` | `boolean` | Adds an 8px spacer below the header so the next content isn't flush against it. Default `true`. |

`<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](https://docs.glassly.ai/app-devs/core-concepts/webviews/react-webviews.md)
The UI layer overview and its hooks.
- [Two-layer architecture](https://docs.glassly.ai/app-devs/core-concepts/two-layer-architecture.md)
How the UI and background layers split and talk.
