PATTERN Cited by 1 source

Compat native escape hatch¶

Problem¶

A cross-platform UI library (react-strict-dom) maps an HTML subset to native components (RN primitives on mobile, plain HTML on web). But sometimes you need a platform-specific prop or behaviour that the HTML surface doesn't expose:

A React Native component that needs a native-only prop (e.g. onLongPress, underlayColor).
An ARIA attribute that only makes sense on one platform.
A direct override of the mapped-to native component's rendering.

Full ejection to patterns/platform-specific-ts-file-resolution is heavy for small cases — you'd end up with Foo.ts and Foo.native.ts just for one prop difference.

Pattern¶

Use react-strict-dom's compat.native API as the in-component escape hatch. compat.native accepts the normal props plus an as hint, and lets you take over the final render with a function that receives the mapped native props:

export component CustomSpan(...props: FooProps) {
  return (
    <compat.native
      {...props}
      aria-label="label"
      as="span"
    >
      {(nativeProps: React.PropsOf<Text>) => (
        <Text {...nativeProps} />
      )}
    </compat.native>
  );
}

The function receives nativeProps — the props react-strict-dom would have passed to the mapped native component — and you decide what to render. You can pass them through unmodified, extend them with platform-specific props, or wrap them in additional components.

When to reach for this pattern¶

You need one-off platform-specific props that don't warrant a full per-platform file.
You need to extend the mapped native component's props rather than replace it entirely.
You're working within the HTML-subset UI pattern but need fine-grained control at certain points.

When not to¶

Divergence is large enough to justify a per-platform file — use patterns/platform-specific-ts-file-resolution instead.
The prop you're passing is genuinely cross-platform and just needs to be in the HTML subset — consider filing an upstream issue against react-strict-dom.

Why this is better than Platform.OS branching¶

Keeps cross-platform surface consistent — the component still has one name, one import, one type signature.
Explicitly scoped to the compat boundary — readers know where the escape hatch is.
Lets react-strict-dom do the heavy lifting (mapping, styling, accessibility) and only overrides the final render.

Seen in¶

sources/2025-10-02-zalando-accelerating-mobile-app-development-with-rendering-engine-and-react-native — canonical wiki first source. Zalando uses compat.native as one of the three escape hatches (alongside .native.ts file resolution and StyleX) for cross-platform component library needs.