Skip to Content
React SDKSafe Area Insets
View .md

Safe Area Insets in Alien Mini Apps: CSS Variables Guide

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.

What are Safe Area Insets?

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 reads the insets and sets the CSS variables for you:

<AlienProvider>
  {/* --alien-safe-area-inset-* are set before paint */}
  <App />
</AlienProvider>

Available CSS Variables for Safe Area

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). When insets are unavailable the SDK leaves the variables unset, so always pass a 0px fallback — var(--alien-safe-area-inset-top, 0px) — as the examples below do.

Apply Safe Area Insets in Your Layout

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, the inset variables are unset, so your 0px CSS fallbacks apply. Use mockLaunchParamsForDev to simulate device insets:

 
if (process.env.NODE_ENV === 'development') {
  mockLaunchParamsForDev({
    authToken: 'dev-token', // required — without it, launch params stay undefined
    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