VyUI alpha
Composables

useSafeArea

Source
Normalized device safe-area insets — notch, Dynamic Island, home indicator — from the container's global props.

Overview

Lynx has no env(safe-area-inset-*) — the host container injects insets as global props, and each container uses its own key names. useSafeArea normalizes them:

import { useSafeArea } from '@vyui/core'

const { top, bottom } = useSafeArea() // logical px, e.g. { top: 59, bottom: 34 }
  • Sparkling injects topHeight / bottomHeight plus an os prop.
  • Lynx Explorer / Lynx Go inject safeAreaTop / safeAreaBottom.
  • Your own host should follow the Explorer names — see the native host integration guide.
  • Android normalizes to zeros: Android containers inset the LynxView natively, so honoring the props would double-pad.
  • Web / vitest have no lynx global and return zeros, so you can apply the insets unconditionally.

Values are snapshotted once — global props don't change over a page's lifetime.

Providing overrides

An ancestor that knows better can override the container read for its subtree:

import { provideSafeAreaInsets } from '@vyui/core'

provideSafeAreaInsets({ top: 0, bottom: 0 }) // e.g. a fullscreen surface drawing its own chrome

VyApp does this at the root: it provides the container's insets app-wide, and its safe-area="false" prop is the zeros override above.

Signature

useSafeArea(): SafeAreaInsets — { top: number, bottom: number }, resolved from an ancestor provideSafeAreaInsets first, the container's global props otherwise. Call during setup().

Also exported: getSafeAreaInsets() (the raw global-props read, no injection) and getSafeAreaInsetsFromGlobalProps(props) (the pure normalizer, useful in tests).

Related

usePrimitiveElement

Resolve a template ref down to a stable ElementHandle regardless of asChild merging.

useGlobalEvent

Subscribe to a Lynx GlobalEventEmitter event — native-to-JS signals from the host app — with automatic cleanup.