use-dom

O que são Componentes DOM?

Componentes DOM permitem que código web seja executado exatamente como está em um webview em plataformas nativas, enquanto é renderizado como está na web. Isso possibilita o uso de bibliotecas exclusivas da web como recharts, react-syntax-highlighter, ou qualquer biblioteca React para web em seu aplicativo Expo sem modificações.

Quando Usar Componentes DOM

Use componentes DOM quando precisar de:

• Bibliotecas exclusivas da web — Gráficos (recharts, chart.js), realçadores de sintaxe, editores de texto rico, ou qualquer biblioteca que dependa de APIs DOM
• Migração de código web — Traga componentes React para web existentes para o nativo sem reescrever
• Layouts HTML/CSS complexos — Quando recursos CSS não estão disponíveis no React Native
• iframes ou embeds — Incorporar conteúdo externo que requer um contexto de navegador
• Canvas ou WebGL — APIs gráficas da web não disponíveis nativamente

Quando NÃO Usar Componentes DOM

Evite componentes DOM quando:

• Performance nativa é crítica — Webviews adicionam sobrecarga
• UI simples — Componentes React Native são mais eficientes para layouts básicos
• Integração nativa profunda — Use módulos locais em vez disso para APIs nativas
• Rotas de layout — Arquivos _layout não podem ser componentes DOM

Componente DOM Básico

Crie um novo arquivo com a diretiva 'use dom'; no topo:

// 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>
  );
}

Regras para Componentes DOM

1. Deve ter a diretiva 'use dom'; no topo do arquivo
2. Exportação padrão única — Um componente React por arquivo
3. Arquivo próprio — Não pode ser definido inline ou combinado com componentes nativos
4. Apenas props serializáveis — Strings, números, booleanos, arrays, objetos simples
5. Inclua CSS no arquivo do componente — Componentes DOM rodam em contexto isolado

A Prop dom

Todo componente DOM recebe uma prop especial dom para configuração do webview. Sempre a tipe em suas props:

"use dom";

interface Props {
  content: string;
  dom: import("expo/dom").DOMProps;
}

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

Opções Comuns da Prop dom

// Disable body scrolling
<DOMComponent dom={{ scrollEnabled: false }} />

// Flow under the notch (disable safe area insets)
<DOMComponent dom={{ contentInsetAdjustmentBehavior: "never" }} />

// Control size manually
<DOMComponent dom={{ style: { width: 300, height: 400 } }} />

// Combine options
<DOMComponent
  dom={{
    scrollEnabled: false,
    contentInsetAdjustmentBehavior: "never",
    style: { width: '100%', height: 500 }
  }}
/>

Expondo Ações Nativas para o Webview

Passe funções assíncronas como props para expor funcionalidades nativas ao componente DOM:

// app/index.tsx (native)
import { Alert } from "react-native";
import DOMComponent from "@/components/dom-component";

export default function Screen() {
  return (
    <DOMComponent
      showAlert={async (message: string) => {
        Alert.alert("From Web", message);
      }}
      saveData={async (data: { name: string; value: number }) => {
        // Save to native storage, database, etc.
        console.log("Saving:", data);
        return { success: true };
      }}
    />
  );
}

// components/dom-component.tsx
"use dom";

interface Props {
  showAlert: (message: string) => Promise<void>;
  saveData: (data: {
    name: string;
    value: number;
  }) => Promise<{ success: boolean }>;
  dom?: import("expo/dom").DOMProps;
}

export default function DOMComponent({ showAlert, saveData }: Props) {
  const handleClick = async () => {
    await showAlert("Hello from the webview!");
    const result = await saveData({ name: "test", value: 42 });
    console.log("Save result:", result);
  };

  return <button onClick={handleClick}>Trigger Native Action</button>;
}

Usando Bibliotecas Web

Componentes DOM podem usar qualquer biblioteca web:

// components/syntax-highlight.tsx
"use dom";

import SyntaxHighlighter from "react-syntax-highlighter";
import { docco } from "react-syntax-highlighter/dist/esm/styles/hljs";

interface Props {
  code: string;
  language: string;
  dom?: import("expo/dom").DOMProps;
}

export default function SyntaxHighlight({ code, language }: Props) {
  return (

…