Scoped safe-area insets for multi-surface React Native apps

[neo-italolino]

Problem

Uniwind.updateInsets() writes safe-area values to process-global runtime state. This works when an application has one React Native root, but not when multiple React Native surfaces are mounted concurrently.

This occurs in brownfield applications where native navigation hosts several React Native surfaces. Each surface can have different safe-area values based on its native container.

For example:

• Surface A appears above a native tab bar and has bottom: 64.
• Surface B appears without that tab bar and has bottom: 0.
• Both surfaces remain mounted in the same JavaScript runtime.

When Surface B calls Uniwind.updateInsets({ bottom: 0, ... }), classes such as pb-safe and pb-safe-offset-* on Surface A also recalculate using bottom: 0.

Restoring Surface A’s insets when it regains focus reduces the visible impact, but does not solve the underlying issue: safe-area state belongs to a surface or React subtree, while Uniwind stores one value for the entire runtime.

This can also affect transition frames and navigation flows that keep covered surfaces mounted.

Proposed direction: scoped insets

Would Uniwind be open to a scoped-insets API, conceptually similar to scoped themes?

One possible API:

<ScopedInsets insets={insets}>
  <Surface />
</ScopedInsets>

Components inside that subtree would resolve *-safe, *-safe-or-*, and *-safe-offset-* utilities against scoped values.

Components outside it would continue using global values configured through Uniwind.updateInsets(), preserving current single-root behavior.

The API does not necessarily need to know about React Native rootTag or Fabric surface IDs. Brownfield hosts can already obtain per-surface insets using a SafeAreaProvider; they mainly need a way to provide those values to Uniwind for one subtree.

Potential semantics:

1. Scoped values inherit through React context.
2. Nearest scoped value wins.
3. Global Uniwind.updateInsets() remains the fallback.
4. Updating one scope only invalidates inset-dependent styles within that scope.
5. Nested scopes are supported or explicitly disallowed, depending on implementation constraints.

Alternative API

If a provider is undesirable, another possibility is a keyed registry:

Uniwind.updateInsets(insets, { scope: surfaceId });

This could be paired with a provider that selects the active scope.

A context-owned value seems less coupled to Fabric and safer than a process-global registry, but maintainer guidance on what best fits Uniwind’s architecture and Pro native-insets implementation would be appreciated.

Questions

• Should this reuse or extend the existing scoped-theme context?
• Should the same API support both SafeAreaListener integration and Pro native insets?

If this direction is acceptable, I would be happy to work on an implementation after agreeing on API and expected behavior.

[Brentlok]

I understand the use case, but we don’t plan to support scoped insets for now. This would add quite a bit of complexity and ongoing maintenance cost to support a very uncommon multi-surface brownfield setup.

We've introduced ScopedVariables lately so you can built your own safe area utilities around it

@utility pb-safe {
    padding: var(--my-safe-bottom-inset);
}

<ScopedVariables variables={{ '--my-safe-bottom-inset': insets.bottom }}>
    <Header />
    <ScopedVariables variables={{ '--my-safe-bottom-inset': 0 }}>
         <SecondApp />
    </ScopedVariables>
</ScopedVariables>

[neo-italolino]

Wow, that’s helpful 😬 lucky timing, since it looks like this was released yesterday! I’ll give ScopedVariables a try and share feedback here for anyone facing the same scenario.

I understand the decision. Thanks for the guidance!

[neo-italolino]

Follow-up: ScopedVariables worked well for this multi-root use case.

One useful detail: the built-in safe-area utilities resolve env(safe-area-inset-*), so scoped CSS variables do not override those environment values directly. The application utilities need to resolve from the scoped custom properties instead.

With that setup, each mounted root retained its own inset values as expected. Thanks again @Brentlok for pointing us toward the new API, closing this as resolved.