Skip to Content
React SDKSafe Area Insets
View .md

Safe Area Insets

Mobile devices have areas of the screen obscured by system UI — the status bar, camera notch, rounded corners, and home indicator. Your mini app runs in a WebView that spans the full screen, so you need to account for these areas to prevent content from being hidden.

The Alien SDK provides safe area insets from the host app and sets them as CSS custom properties automatically.

How It Works

When AlienProvider mounts, it reads the safe area insets from the launch parameters and sets CSS custom properties on the root element (<html>). This happens synchronously before paint, so there’s no layout shift.

┌──────────────────────────┐
│      status bar (top)    │  ← --alien-safe-area-inset-top
├──────────────────────────┤
│                          │
│     your app content     │
│                          │
├──────────────────────────┤
│   home indicator (bottom)│  ← --alien-safe-area-inset-bottom
└──────────────────────────┘

No extra setup needed — AlienProvider handles it:

CSS Variables

VariableDescription
--alien-safe-area-inset-topDistance from top (status bar, notch)
--alien-safe-area-inset-rightDistance from right edge
--alien-safe-area-inset-bottomDistance from bottom (home indicator)
--alien-safe-area-inset-leftDistance from left edge

Values are in CSS pixels (e.g., 47px). Defaults to 0px if insets are unavailable.

Usage

Padding

The most common approach — add padding so content doesn’t overlap system UI:

.page {
  padding-top: var(--alien-safe-area-inset-top, 0px);
  padding-bottom: var(--alien-safe-area-inset-bottom, 0px);
}

Fixed Headers and Footers

For fixed-position elements, add the inset to your existing spacing:

.header {
  position: fixed;
  top: 0;
  padding-top: calc(
    12px + var(--alien-safe-area-inset-top, 0px)
  );
}
 
.bottom-nav {
  position: fixed;
  bottom: 0;
  padding-bottom: calc(
    8px + var(--alien-safe-area-inset-bottom, 0px)
  );
}

Tailwind CSS

Use arbitrary values in Tailwind classes:

<div className="pt-[var(--alien-safe-area-inset-top,0px)]
  pb-[var(--alien-safe-area-inset-bottom,0px)]">
  <App />
</div>

Or define utilities in your CSS:

@layer utilities {
  .safe-top {
    padding-top: var(--alien-safe-area-inset-top, 0px);
  }
  .safe-bottom {
    padding-bottom: var(--alien-safe-area-inset-bottom, 0px);
  }
}

JavaScript Access

If you need the raw values in JavaScript, use useLaunchParams:

 
function MyComponent() {
  const params = useLaunchParams();
  const insets = params?.safeAreaInsets;
  // { top: 47, right: 0, bottom: 34, left: 0 }
}

SafeAreaInsets Type

interface SafeAreaInsets {
  top: number;
  right: number;
  bottom: number;
  left: number;
}

All values are in CSS pixels.

Testing in Development

When running outside the Alien app, insets default to 0px. Use mockLaunchParamsForDev to simulate device insets:

 
if (process.env.NODE_ENV === 'development') {
  mockLaunchParamsForDev({
    safeAreaInsets: {
      top: 47,    // iPhone notch
      right: 0,
      bottom: 34, // Home indicator
      left: 0,
    },
  });
}

Common Patterns

Full-screen scrollable content with safe edges:

.app {
  min-height: 100dvh;
  padding-top: var(--alien-safe-area-inset-top, 0px);
  padding-bottom: var(--alien-safe-area-inset-bottom, 0px);
}

Sticky input bar at the bottom:

.input-bar {
  position: sticky;
  bottom: 0;
  padding-bottom: var(--alien-safe-area-inset-bottom, 0px);
}

Next Steps

Last updated on
App LifecycleAuthentication