Vize
Safe Area
Region exposing env(safe-area-inset-*) as CSS variables, data attributes, and optional padding.
| Package | @vizejs/ui/safe-area |
| Maturity | stable |
| Own the source | vize lib pull safe-area |
| Requires | — |
| Aliases | safe area, notch insets, env safe-area-inset, home indicator padding |
| Covers | CSS env(safe-area-inset-*), Ionic safe area, react-native-safe-area-context |
Usage
import { SafeArea } from "@vizejs/ui/safe-area";
Or copy the source into your project with vize lib pull safe-area (see Source Distribution).
API
SafeArea
Source: src/families/layout/safe-area/safe-area.vue
Props
| Prop | Type | Default | Description |
|---|---|---|---|
as |
PrimitiveAs |
"div" |
Element or component to render. |
edges |
readonly SafeAreaEdge[] |
["top", "right", "bottom", "left"] |
Edges this region respects (published as data-edges and applied by apply). |
apply |
"margin" | "none" | "padding" |
"none" |
Apply the selected insets as inline padding or margin; "none" only exposes CSS variables. |
Slots
| Slot | Slot props | Description |
|---|---|---|
default |
{ readonly insets: SafeAreaEdgeInsets } |
Region contents with the measured insets (zero on the server and before hydration). |
Behavior
Normative state x input -> outcome table for safe-area.vue and
useSafeAreaInsets (@vizejs/ui/safe-area). Every row is proven by the named
test in safe-area.test.ts or safe-area-ssr.test.ts; compile-only assertions
live in safe-area.types.test-d.ts.
| # | State | Input | Outcome | Proven by |
|---|---|---|---|---|
| SA1 | any | render | --vize-safe-area-inset-* map to env(safe-area-inset-*, 0px); data-edges lists edges; apply pads/margins only those edges |
exposes env() insets as CSS variables and applies only the selected edges |
| SA2 | mounted | microtask / resize | a hidden probe measures insets after hydration; non-zero edges appear in data-insets and the slot; unmount removes the probe |
measures insets after a microtask, publishes non-zero edges, and re-measures on resize |
| SA3 | composable | scope / no document | useSafeAreaInsets runs in any effect scope, stops with it, and stays at zero without a document |
useSafeAreaInsets works in any scope and is inert without a document |
| SA4 | slot | render | the default slot renders contents with typed insets | renders slot content with typed insets |
| SA5 | SSR / hydration | isolated requests | byte-identical markup with CSS variables and no measured data; hydration without diagnostics | renders byte-identical safe-area markup and hydrates without mismatches |
Non-zero insets require <meta name="viewport" content="viewport-fit=cover">.
The subpath is tree-shakable and ships no CSS.