Embed Web Libraries in Native Mobile Apps with DOM Components

Covers Expo's DOM Components feature: web code that runs verbatim in a webview on native platforms while rendering as-is on web, letting web-only React libraries (recharts, react-syntax-highlighter, and similar) run inside an Expo app unmodified.

Use DOM components for web-only libraries dependent on DOM APIs (charts, syntax highlighters, rich text editors), migrating existing React web components without a rewrite, complex HTML/CSS layouts unavailable in React Native, iframes/embeds needing a browser context, or Canvas/WebGL. Avoid them where native performance is critical (webviews add overhead), for simple UI (native components are more efficient), for deep native-API integration (use local modules instead), or for _layout route files, which cannot be DOM components.

// components/WebChart.tsx
"use dom";

export default function WebChart({
  data,
}: {
  data: number[];
  dom: import("expo/dom").DOMProps;
}) {
  return (
    <div style={{ padding: 20 }}>
      <h2>Chart Data</h2>
      <ul>
        {data.map((value, i) => (
          <li key={i}>{value}</li>
        ))}
      </ul>
    </div>
  );
}

Every DOM component file must start with a 'use dom'; directive, export exactly one React component as default, live in its own file (never inline or combined with native components), accept only serializable props (strings, numbers, booleans, arrays, plain objects), and import its own CSS - DOM components run in an isolated JS context. Every DOM component also receives a special dom prop (typed via import("expo/dom").DOMProps) for webview configuration - options include scrollEnabled, contentInsetAdjustmentBehavior: "never" (to flow under the notch), and a style object for manual sizing.

Native functionality is exposed to the webview by passing async functions as props from the native parent (e.g. showAlert, saveData callbacks a DOM component can call and await). CSS can be imported directly in the component file or written as inline styles/CSS-in-JS. The expo-router <Link /> component and useRouter() work directly inside DOM components, but several router hooks needing synchronous native routing state - useLocalSearchParams, useGlobalSearchParams, usePathname, useSegments, useRootNavigation, useRootNavigationState - don't work directly and must instead be read in the native parent and passed down as props. An IS_DOM export from expo/dom detects whether code is currently running inside a DOM component. Assets should be require()d and bundled with the component rather than served from the public directory.

Platform behavior differs: iOS renders in WKWebView, Android in WebView, and web renders as-is with no webview wrapper (the dom prop is simply ignored there).

Use DOM components to bring web-only React libraries or complex HTML/CSS into an Expo app without a native rewrite. Avoid them for simple UI, performance-critical surfaces, deep native API access, or layout route files. Keep them focused - don't put entire screens inside a webview - and remember the webview has its own JS context with no direct state sharing with native code.

Input is a React web component (or web library usage) that needs to run inside an Expo app. Output is a 'use dom'-directived component file that native screens import and render like any other component, configured via the dom prop.

Works with any web-only React library (recharts, react-syntax-highlighter, etc.), expo-router's <Link />/useRouter(), and native functionality exposed via async function props from the native parent.

Expo/React Native developers who need a web-only library or existing React web component running inside their app without a native rewrite, and want the DOM-component rules, prop patterns, and router workarounds without re-deriving them from Expo's documentation.