1---
2name: use-dom
3description: Use Expo DOM components to run web code in a webview on native and as-is on web. Migrate web code to native incrementally.
4version: 1.0.0
5license: MIT
6---
7 
8## What are DOM Components?
9 
10DOM components allow web code to run verbatim in a webview on native platforms while rendering as-is on web. This enables using web-only libraries like `recharts`, `react-syntax-highlighter`, or any React web library in your Expo app without modification.
11 
12## When to Use DOM Components
13 
14Use DOM components when you need:
15 
16- **Web-only libraries** — Charts (recharts, chart.js), syntax highlighters, rich text editors, or any library that depends on DOM APIs
17- **Migrating web code** — Bring existing React web components to native without rewriting
18- **Complex HTML/CSS layouts** — When CSS features aren't available in React Native
19- **iframes or embeds** — Embedding external content that requires a browser context
20- **Canvas or WebGL** — Web graphics APIs not available natively
21 
22## When NOT to Use DOM Components
23 
24Avoid DOM components when:
25 
26- **Native performance is critical** — Webviews add overhead
27- **Simple UI** — React Native components are more efficient for basic layouts
28- **Deep native integration** — Use local modules instead for native APIs
29- **Layout routes** — `_layout` files cannot be DOM components
30 
31## Basic DOM Component
32 
33Create a new file with the `'use dom';` directive at the top:
34 
35```tsx
36// components/WebChart.tsx
37"use dom";
38 
39export default function WebChart({
40  data,
41}: {
42  data: number[];
43  dom: import("expo/dom").DOMProps;
44}) {
45  return (
46    <div style={{ padding: 20 }}>
47      <h2>Chart Data</h2>
48      <ul>
49        {data.map((value, i) => (
50          <li key={i}>{value}</li>
51        ))}
52      </ul>
53    </div>
54  );
55}
56```
57 
58## Rules for DOM Components
59 
601. **Must have `'use dom';` directive** at the top of the file
612. **Single default export** — One React component per file
623. **Own file** — Cannot be defined inline or combined with native components
634. **Serializable props only** — Strings, numbers, booleans, arrays, plain objects
645. **Include CSS in the component file** — DOM components run in isolated context
65 
66## The `dom` Prop
67 
68Every DOM component receives a special `dom` prop for webview configuration. Always type it in your props:
69 
70```tsx
71"use dom";
72 
73interface Props {
74  content: string;
75  dom: import("expo/dom").DOMProps;
76}
77 
78export default function MyComponent({ content }: Props) {
79  return <div>{content}</div>;
80}
81```
82 
83### Common `dom` Prop Options
84 
85```tsx
86// Disable body scrolling
87<DOMComponent dom={{ scrollEnabled: false }} />
88 
89// Flow under the notch (disable safe area insets)
90<DOMComponent dom={{ contentInsetAdjustmentBehavior: "never" }} />
91 
92// Control size manually
93<DOMComponent dom={{ style: { width: 300, height: 400 } }} />
94 
95// Combine options
96<DOMComponent
97  dom={{
98    scrollEnabled: false,
99    contentInsetAdjustmentBehavior: "never",
100    style: { width: '100%', height: 500 }
101  }}
102/>
103```
104 
105## Exposing Native Actions to the Webview
106 
107Pass async functions as props to expose native functionality to the DOM component:
108 
109```tsx
110// app/index.tsx (native)
111import { Alert } from "react-native";
112import DOMComponent from "@/components/dom-component";
113 
114export default function Screen() {
115  return (
116    <DOMComponent
117      showAlert={async (message: string) => {
118        Alert.alert("From Web", message);
119      }}
120      saveData={async (data: { name: string; value: number }) => {
121        // Save to native storage, database, etc.
122        console.log("Saving:", data);
123        return { success: true };
124      }}
125    />
126  );
127}
128```
129 
130```tsx
131// components/dom-component.tsx
132"use dom";
133 
134interface Props {
135  showAlert: (message: string) => Promise<void>;
136  saveData: (data: {
137    name: string;
138    value: number;
139  }) => Promise<{ success: boolean }>;
140  dom?: import("expo/dom").DOMProps;
141}
142 
143export default function DOMComponent({ showAlert, saveData }: Props) {
144  const handleClick = async () => {
145    await showAlert("Hello from the webview!");
146    const result = await saveData({ name: "test", value: 42 });
147    console.log("Save result:", result);
148  };
149 
150  return <button onClick={handleClick}>Trigger Native Action</button>;
151}
152```
153 
154## Using Web Libraries
155 
156DOM components can use any web library:
157 
158```tsx
159// components/syntax-highlight.tsx
160"use dom";
161 
162import SyntaxHighlighter from "react-syntax-highlighter";
163import { docco } from "react-syntax-highlighter/dist/esm/styles/hljs";
164 
165interface Props {
166  code: string;
167  language: string;
168  dom?: import("expo/dom").DOMProps;
169}
170 
171export default function SyntaxHighlight({ code, language }: Props) {
172  return (
173    <SyntaxHighlighter language={language} style={docco}>
174      {code}
175    </SyntaxHighlighter>
176  );
177}
178```
179 
180```tsx
181// components/chart.tsx
182"use dom";
183 
184import {
185  LineChart,
186  Line,
187  XAxis,
188  YAxis,
189  CartesianGrid,
190  Tooltip,
191} from "recharts";
192 
193interface Props {
194  data: Array<{ name: string; value: number }>;
195  dom: import("expo/dom").DOMProps;
196}
197 
198export default function Chart({ data }: Props) {
199  return (
200    <LineChart width={400} height={300} data={data}>
201      <CartesianGrid strokeDasharray="3 3" />
202      <XAxis dataKey="name" />
203      <YAxis />
204      <Tooltip />
205      <Line type="monotone" dataKey="value" stroke="#8884d8" />
206    </LineChart>
207  );
208}
209```
210 
211## CSS in DOM Components
212 
213CSS imports must be in the DOM component file since they run in isolated context:
214 
215```tsx
216// components/styled-component.tsx
217"use dom";
218 
219import "@/styles.css"; // CSS file in same directory
220 
221export default function StyledComponent({
222  dom,
223}: {
224  dom: import("expo/dom").DOMProps;
225}) {
226  return (
227    <div className="container">
228      <h1 className="title">Styled Content</h1>
229    </div>
230  );
231}
232```
233 
234Or use inline styles / CSS-in-JS:
235 
236```tsx
237"use dom";
238 
239const styles = {
240  container: {
241    padding: 20,
242    backgroundColor: "#f0f0f0",
243  },
244  title: {
245    fontSize: 24,
246    color: "#333",
247  },
248};
249 
250export default function StyledComponent({
251  dom,
252}: {
253  dom: import("expo/dom").DOMProps;
254}) {
255  return (
256    <div style={styles.container}>
257      <h1 style={styles.title}>Styled Content</h1>
258    </div>
259  );
260}
261```
262 
263## Expo Router in DOM Components
264 
265The expo-router `<Link />` component and router API work inside DOM components:
266 
267```tsx
268"use dom";
269 
270import { Link, useRouter } from "expo-router";
271 
272export default function Navigation({
273  dom,
274}: {
275  dom: import("expo/dom").DOMProps;
276}) {
277  const router = useRouter();
278 
279  return (
280    <nav>
281      <Link href="/about">About</Link>
282      <button onClick={() => router.push("/settings")}>Settings</button>
283    </nav>
284  );
285}
286```
287 
288### Router APIs That Require Props
289 
290These hooks don't work directly in DOM components because they need synchronous access to native routing state:
291 
292- `useLocalSearchParams()`
293- `useGlobalSearchParams()`
294- `usePathname()`
295- `useSegments()`
296- `useRootNavigation()`
297- `useRootNavigationState()`
298 
299**Solution:** Read these values in the native parent and pass as props:
300 
301```tsx
302// app/[id].tsx (native)
303import { useLocalSearchParams, usePathname } from "expo-router";
304import DOMComponent from "@/components/dom-component";
305 
306export default function Screen() {
307  const { id } = useLocalSearchParams();
308  const pathname = usePathname();
309 
310  return <DOMComponent id={id as string} pathname={pathname} />;
311}
312```
313 
314```tsx
315// components/dom-component.tsx
316"use dom";
317 
318interface Props {
319  id: string;
320  pathname: string;
321  dom?: import("expo/dom").DOMProps;
322}
323 
324export default function DOMComponent({ id, pathname }: Props) {
325  return (
326    <div>
327      <p>Current ID: {id}</p>
328      <p>Current Path: {pathname}</p>
329    </div>
330  );
331}
332```
333 
334## Detecting DOM Environment
335 
336Check if code is running in a DOM component:
337 
338```tsx
339"use dom";
340 
341import { IS_DOM } from "expo/dom";
342 
343export default function Component({
344  dom,
345}: {
346  dom?: import("expo/dom").DOMProps;
347}) {
348  return <div>{IS_DOM ? "Running in DOM component" : "Running natively"}</div>;
349}
350```
351 
352## Assets
353 
354Prefer requiring assets instead of using the public directory:
355 
356```tsx
357"use dom";
358 
359// Good - bundled with the component
360const logo = require("../assets/logo.png");
361 
362export default function Component({
363  dom,
364}: {
365  dom: import("expo/dom").DOMProps;
366}) {
367  return <img src={logo} alt="Logo" />;
368}
369```
370 
371## Usage from Native Components
372 
373Import and use DOM components like regular components:
374 
375```tsx
376// app/index.tsx
377import { View, Text } from "react-native";
378import WebChart from "@/components/web-chart";
379import CodeBlock from "@/components/code-block";
380 
381export default function HomeScreen() {
382  return (
383    <View style={{ flex: 1 }}>
384      <Text>Native content above</Text>
385 
386      <WebChart data={[10, 20, 30, 40, 50]} dom={{ style: { height: 300 } }} />
387 
388      <CodeBlock
389        code="const x = 1;"
390        language="javascript"
391        dom={{ scrollEnabled: true }}
392      />
393 
394      <Text>Native content below</Text>
395    </View>
396  );
397}
398```
399 
400## Platform Behavior
401 
402| Platform | Behavior                            |
403| -------- | ----------------------------------- |
404| iOS      | Rendered in WKWebView               |
405| Android  | Rendered in WebView                 |
406| Web      | Rendered as-is (no webview wrapper) |
407 
408On web, the `dom` prop is ignored since no webview is needed.
409 
410## Tips
411 
412- DOM components hot reload during development
413- Keep DOM components focused — don't put entire screens in webviews
414- Use native components for navigation chrome, DOM components for specialized content
415- Test on all platforms — web rendering may differ slightly from native webviews
416- Large DOM components may impact performance — profile if needed
417- The webview has its own JavaScript context — cannot directly share state with native
418