use-dom

Files (1)

• SKILL.md

SKILL.md (first lines)

# DOM Components in React Native ('use dom')

## Overview

The `'use dom'` directive lets you embed web code inside React Native apps. Components marked with `'use dom'` render in a native webview (WKWebView on iOS, WebView on Android), giving you access to the full browser DOM while keeping the rest of your app native.

**Core principle:** Use `'use dom'` as a bridge to web-only libraries that have no React Native equivalent. The DOM component runs in an isolated webview, communicating with your native app through serializable props.

## When to Use

- Rendering charts with web libraries (recharts, Chart.js, D3)
- Syntax highlighting code blocks (Prism, Shiki, highlight.js)
- Rich text editors (TipTap, Lexical, Quill)
- Embedding maps with web map libraries (Leaflet, Mapbox GL JS)
- Rendering complex HTML/CSS content (markdown, documentation)
- Using any npm package that depends on browser APIs (DOM, Canvas, WebGL)

### When NOT to Use

- Simple UI components (use React Native components)
- Performance-critical animations (use Reanimated)
- Components needing native device APIs (camera, sensors)
- Content that could be rendered with React Native `Text`/`View`

## Basic Usage

Add `'use dom'` as the first line of a component file:

```tsx
// components/WebChart.tsx
'use dom';

import { BarChart, Bar, XAxis, YAxis, Tooltip } from 'recharts';

type Props = {
  data: Array<{ name: string; value: number }>;
  dom?: import('expo/dom').DOMProps;
};

export default function WebChart({ data }: Props) {
  return (
    <BarChart width={350} height={250} data={data}>
      <XAxis dataKey="name" />
      <YAxis />
      <Tooltip />
      <Bar dataKey="value" fill="#3b82f6" />
    </BarChart>
  );
}
```

Use it in your native React Native screen:

```tsx
// app/analytics.tsx
import WebChart from '../components/WebChart';

const chartData = [
  { name: 'Mon', value: 120 },
  { name: 'Tue', value: 250 },
  { name: 'Wed', value: 180 },
  { name: 'Thu', value: 310 },
  { name: 'Fri', value: 420 },
];

export default function AnalyticsScreen() {
  return (
    <View style={{ flex: 1, padding: 16 }}>
      <Text style={{ fontSize: 20, fontWeight: 'bold', marginBottom: 16 }}>
        Weekly Activity
      </Text>
      <WebChart data={chartData} />
    </View>
  );
}
```

## The DOMProps Type

Every `'use dom'` component receives an optional `dom` prop for controlling the webview:

```tsx
'use dom';

type Props = {
  content: string;
  dom?: import('expo/dom').DOMProps;
};

export default function MyDomComponent({ content }: Props) {
  return <div>{content}</div>;
}
```

The `dom` prop is injected automatically by the framework. You do not pass it manually. Include it in the type definition so TypeScript knows about it.

### DOMProps Options

```tsx
// In your native component:
<WebChart
  data={data}
  dom={{
    scrollEnabled: true,       // Allow scrolling within the webview
    matchContents: true,       // Auto-size webview to content height
  }}
/>
```

## Serializable Props Requirement

All props passed to `'use dom'` components must be JSON-serializable. The props cross a native-to-webview bridge.

### What Works

```tsx
// Primitives
<DomComponent count={42} />
<DomComponent label="hello" />

From bidah/react-native-hifi, MIT.

More from bidah/react-native-hifi