feat: add syncHostStyles API to disable iframe style sync

Author: chrisvxd

apps/docs/pages/docs/api-reference/components/puck.mdx

@@ -173,16 +173,23 @@ export function Editor() {
 
 #### iframe params
 
-| Param                 | Example          | Type    | Status |
-| --------------------- | ---------------- | ------- | ------ |
-| [`enabled`](#enabled) | `enabled: false` | boolean | -      |
+| Param                               | Example                 | Type    | Status |
+| ----------------------------------- | ----------------------- | ------- | ------ |
+| [`enabled`](#enabled)               | `enabled: false`        | boolean | -      |
+| [`syncHostStyles`](#syncHostStyles) | `syncHostStyles: false` | boolean | -      |
 
 ##### `enabled`
 
 Render the Puck preview within iframe. Defaults to `true`.
 
 Disabling iframes will also disable [viewports](#viewports).
 
+##### `syncHostStyles`
+
+Sync the host styles to the iframe. Defaults to `true`.
+
+If this isn't working, you may need to inject styles manually using the iframe [override API](/docs/api-reference/overrides/iframe), or make use of a [plugin](/docs/extending-puck/plugins).
+
 ### `initialHistory`
 
 Sets the undo/redo Puck history state when using the `usePuck` [history API](/docs/api-reference/functions/use-puck#history).

packages/core/components/AutoFrame/index.tsx

@@ -60,16 +60,24 @@ const CopyHostStyles = ({
   children,
   debug = false,
   onStylesLoaded = () => null,
+  enabled = true,
 }: {
   children: ReactNode;
   debug?: boolean;
   onStylesLoaded?: () => void;
+  enabled?: boolean;
 }) => {
   const { document: doc, window: win } = useFrame();
 
   useEffect(() => {
     if (!win || !doc) {
-      return () => {};
+      return;
+    }
+
+    if (!enabled) {
+      onStylesLoaded();
+
+      return;
     }
 
     let elements: { original: HTMLElement; mirror: HTMLElement }[] = [];
@@ -303,6 +311,7 @@ export type AutoFrameProps = {
   debug?: boolean;
   id?: string;
   onStylesLoaded?: () => void;
+  syncHostStyles?: boolean;
 };
 
 type AutoFrameContext = {
@@ -320,6 +329,7 @@ function AutoFrame({
   debug,
   id,
   onStylesLoaded,
+  syncHostStyles = true,
   ...props
 }: AutoFrameProps) {
   const [loaded, setLoaded] = useState(false);
@@ -351,7 +361,11 @@ function AutoFrame({
     >
       <autoFrameContext.Provider value={ctx}>
         {loaded && mountTarget && (
-          <CopyHostStyles debug={debug} onStylesLoaded={onStylesLoaded}>
+          <CopyHostStyles
+            debug={debug}
+            onStylesLoaded={onStylesLoaded}
+            enabled={syncHostStyles}
+          >
             {createPortal(children, mountTarget)}
           </CopyHostStyles>
         )}

packages/core/components/Puck/components/Preview/index.tsx

@@ -49,6 +49,7 @@ export const Preview = ({ id = "puck-preview" }: { id?: string }) => {
           onStylesLoaded={() => {
             setStatus("READY");
           }}
+          syncHostStyles={iframe.syncHostStyles}
         >
           <autoFrameContext.Consumer>
             {({ document }) => {

packages/core/components/Puck/index.tsx

@@ -86,9 +86,7 @@ export function Puck<
   headerTitle,
   headerPath,
   viewports = defaultViewports,
-  iframe = {
-    enabled: true,
-  },
+  iframe: _iframe,
   dnd,
   initialHistory,
 }: {
@@ -133,6 +131,12 @@ export function Puck<
     })
   );
 
+  const iframe: IframeConfig = {
+    enabled: true,
+    syncHostStyles: true,
+    ..._iframe,
+  };
+
   const [initialAppState] = useState<AppState<UserData>>(() => {
     const initial = { ...defaultAppState.ui, ...initialUi };
 

packages/core/types/API/index.ts

@@ -13,6 +13,7 @@ export type Permissions = {
 
 export type IframeConfig = {
   enabled?: boolean;
+  syncHostStyles?: boolean;
 };
 
 export type OnAction<UserData extends Data = Data> = (