Integración de Tema

Mantén tu plugin sincronizado visualmente con el modo claro y oscuro del admin de Whatalo usando el App Bridge.

El admin de Whatalo soporta modo claro y oscuro. Cuando el comerciante cambia el tema, el admin envía un payload de contexto actualizado a tu plugin en tiempo real. El App Bridge maneja la sincronización para que tu UI siempre coincida con el shell que la rodea.

Cómo Funciona

El admin incluye theme: "light" | "dark" en el mensaje inicial whatalo:context.
Un MutationObserver en el admin detecta cambios de atributo de tema en <html>.
Cuando el tema cambia, el host envía un nuevo mensaje whatalo:context al iframe de tu plugin.
El bridge establece document.documentElement.setAttribute("data-theme", theme) en la raíz de tu documento.
Tus reglas CSS [data-theme="dark"] se activan automáticamente.

Opción 1: Hook `useThemeSync` (Recomendado)

La plantilla del plugin incluye un hook useThemeSync en ./components/whatalo-ui que maneja la actualización del atributo por ti:

import { useThemeSync } from "./components/whatalo-ui";

function App() {
  // Sincroniza data-theme en document.documentElement automáticamente
  useThemeSync();

  return <div className="mi-plugin">...</div>;
}

Llama este hook una sola vez en la raíz de tu aplicación.

Opción 2: Leer el Valor del Tema Directamente

import { useAppBridge } from "@whatalo/plugin-sdk/bridge";

function MiComponente() {
  const { theme } = useAppBridge();

  return (
    <div className={theme === "dark" ? "modo-oscuro" : "modo-claro"}>
      ...
    </div>
  );
}

Patrón de Propiedades CSS Personalizadas

Los componentes WUI de la plantilla usan propiedades CSS personalizadas activadas por el atributo data-theme:

/* Predeterminado (claro) */
:root {
  --wui-bg: #ffffff;
  --wui-text: #1a1a2e;
  --wui-border: #e2e8f0;
}

/* Modo oscuro — se activa cuando el admin está en modo oscuro */
[data-theme="dark"] {
  --wui-bg: #1a1a2e;
  --wui-text: #e8e8e8;
  --wui-border: #2d3748;
}

Usa estos tokens en los estilos propios de tu plugin para lograr un tema consistente sin hardcodear valores de color.

Fondo del Iframe

Tu iframe de plugin tiene overflow: hidden y fondo transparente. El shell del admin gestiona el scroll — el contenido de tu plugin debe llenar la altura del iframe (usa la acción resize o useAutoResize).

Los iframes de modal abiertos via bridge.modal.open() no reciben contexto del App Bridge directamente. El bridge pasa el tema actual como parámetro de query URL:

https://tu-plugin.ejemplo.com/modal/pedido/123?theme=dark

useThemeSync lee primero el parámetro ?theme= y luego recurre al contexto del bridge si el parámetro no está presente. Esto significa que el mismo hook funciona de manera idéntica tanto en tu iframe principal como en cualquier iframe de modal.

Cómo Funciona

Opción 1: Hook useThemeSync (Recomendado)

Opción 2: Leer el Valor del Tema Directamente

Patrón de Propiedades CSS Personalizadas

Fondo del Iframe

Tema en Iframes de Modal

On this page

Opción 1: Hook `useThemeSync` (Recomendado)