tellthemachines · Mar 19, 2026 · Mar 19, 2026
diff --git a/packages/block-editor/src/components/block-list/block.js b/packages/block-editor/src/components/block-list/block.js
@@ -23,7 +23,7 @@ import {
 } from '@wordpress/blocks';
 import { withFilters } from '@wordpress/components';
 import { withDispatch, useSelect } from '@wordpress/data';
-import { compose } from '@wordpress/compose';
+import { compose, useRefEffect } from '@wordpress/compose';
 import { safeHTML } from '@wordpress/dom';
 
 /**
@@ -741,10 +741,19 @@ function BlockListBlockProvider( props ) {
 		[ clientId, rootClientId ]
 	);
 
+	const defaultViewRef = useRefEffect( ( element ) => {
+		if ( element ) {
+			const { ownerDocument } = element;
+			const { defaultView } = ownerDocument;
+			defaultViewRef.current = defaultView;
+		}
+	}, [] );
+
 	// Use block visibility hook with data from existing useSelect to avoid extra subscription
 	const { isBlockCurrentlyHidden } = useBlockVisibility( {
 		blockVisibility: selectedProps?.blockVisibility,
 		deviceType: selectedProps?.deviceType,
+		view: defaultViewRef.current,
 	} );
 
 	// Users of the editor.BlockListBlock filter used to be able to

diff --git a/packages/block-editor/src/components/block-list/use-block-props/index.js b/packages/block-editor/src/components/block-list/use-block-props/index.js
@@ -9,7 +9,7 @@ import clsx from 'clsx';
 import { useContext } from '@wordpress/element';
 import { __, sprintf } from '@wordpress/i18n';
 import { __unstableGetBlockProps as getBlockProps } from '@wordpress/blocks';
-import { useMergeRefs, useDisabled } from '@wordpress/compose';
+import { useMergeRefs, useDisabled, useRefEffect } from '@wordpress/compose';
 import warning from '@wordpress/warning';
 
 /**
@@ -107,13 +107,22 @@ export function useBlockProps( props = {}, { __unstableIsHtml } = {} ) {
 		deviceType,
 	} = useContext( PrivateBlockContext );
 
+	const defaultViewRef = useRefEffect( ( element ) => {
+		if ( element ) {
+			const { ownerDocument } = element;
+			const { defaultView } = ownerDocument;
+			defaultViewRef.current = defaultView;
+		}
+	}, [] );
+
 	// translators: %s: Type of block (i.e. Text, Image etc)
 	const blockLabel = sprintf( __( 'Block: %s' ), blockTitle );
 	const htmlSuffix = mode === 'html' && ! __unstableIsHtml ? '-visual' : '';
 	const ffDragRef = useFirefoxDraggableCompatibility();
 	const isHoverEnabled = ! isWithinSectionBlock;
 	const mergedRefs = useMergeRefs( [
 		props.ref,
+		defaultViewRef,
 		useFocusFirstElement( { clientId, initialPosition } ),
 		useBlockRefProvider( clientId ),
 		useFocusHandler( clientId ),
@@ -144,6 +153,7 @@ export function useBlockProps( props = {}, { __unstableIsHtml } = {} ) {
 	const { isBlockCurrentlyHidden } = useBlockVisibility( {
 		blockVisibility,
 		deviceType,
+		view: defaultViewRef.current,
 	} );
 
 	// Ensures it warns only inside the `edit` implementation for the block.

diff --git a/packages/block-editor/src/components/block-visibility/use-block-visibility.js b/packages/block-editor/src/components/block-visibility/use-block-visibility.js
@@ -14,16 +14,18 @@ import { BLOCK_VISIBILITY_VIEWPORTS } from './constants';
  * @param {Object}         options                 Parameters to avoid extra store subscriptions.
  * @param {Object|boolean} options.blockVisibility Block visibility metadata.
  * @param {string}         options.deviceType      Current device type ('desktop', 'tablet', 'mobile').
+ * @param {Window?}        options.view            Window instance in which to perform viewport matching
  * @return {Object} Object with `isBlockCurrentlyHidden` (boolean) and `currentViewport` (string) properties.
  */
 export default function useBlockVisibility( options = {} ) {
 	const {
 		blockVisibility = undefined,
 		deviceType = BLOCK_VISIBILITY_VIEWPORTS.desktop.key,
+		view = window,
 	} = options;
 
-	const isLargerThanMobile = useViewportMatch( 'mobile', '>=' ); // >= 480px
-	const isLargerThanTablet = useViewportMatch( 'medium', '>=' ); // >= 782px
+	const isLargerThanMobile = useViewportMatch( 'mobile', '>=', view ); // >= 480px
+	const isLargerThanTablet = useViewportMatch( 'medium', '>=', view ); // >= 782px
 
 	/*
 	 * Priority:

diff --git a/packages/block-editor/src/components/iframe/index.js b/packages/block-editor/src/components/iframe/index.js
@@ -8,12 +8,7 @@ import clsx from 'clsx';
  */
 import { useState, createPortal, forwardRef } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
-import {
-	useMergeRefs,
-	useRefEffect,
-	useDisabled,
-	useViewportMatch,
-} from '@wordpress/compose';
+import { useMergeRefs, useRefEffect, useDisabled } from '@wordpress/compose';
 import { __experimentalStyleProvider as StyleProvider } from '@wordpress/components';
 import { useSelect } from '@wordpress/data';
 
@@ -25,8 +20,6 @@ import { getCompatibilityStyles } from './get-compatibility-styles';
 import { useScaleCanvas } from './use-scale-canvas';
 import { store as blockEditorStore } from '../../store';
 
-const ViewportWidthProvider = useViewportMatch.__experimentalWidthProvider;
-
 function bubbleEvent( event, Constructor, frame ) {
 	const init = {};
 
@@ -274,7 +267,6 @@ function Iframe( {
 	const {
 		contentResizeListener,
 		containerResizeListener,
-		containerWidth,
 		isZoomedOut,
 		scaleContainerWidth,
 	} = useScaleCanvas( {
@@ -355,9 +347,7 @@ function Iframe( {
 						>
 							{ contentResizeListener }
 							<StyleProvider document={ iframeDocument }>
-								<ViewportWidthProvider value={ containerWidth }>
-									{ children }
-								</ViewportWidthProvider>
+								{ children }
 							</StyleProvider>
 						</body>,
 						iframeDocument.documentElement

diff --git a/packages/block-editor/src/components/iframe/use-scale-canvas.js b/packages/block-editor/src/components/iframe/use-scale-canvas.js
@@ -484,7 +484,6 @@ export function useScaleCanvas( {
 	return {
 		isZoomedOut,
 		scaleContainerWidth,
-		containerWidth,
 		contentResizeListener,
 		containerResizeListener,
 	};

diff --git a/packages/compose/CHANGELOG.md b/packages/compose/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### New Features
+
+-   Hooks `useMediaQuery` and `useViewportMatch` accept a new optional `view` argument of type `Window`, which enables consumers to perform media queries in a window other than the global one (e.g. an iframe) ([#76446](https://github.com/WordPress/gutenberg/pull/76446)).
+
 ## 7.40.0 (2026-02-18)
 
 ## 7.39.0 (2026-01-29)

diff --git a/packages/compose/README.md b/packages/compose/README.md
@@ -431,6 +431,7 @@ Runs a media query and returns its value when it changes.
 _Parameters_
 
 -   _query_ `[string]`: Media Query.
+-   _view_ `[Window]`: Window instance, else default to global window
 
 _Returns_
 
@@ -592,6 +593,7 @@ _Parameters_
 
 -   _breakpoint_ `WPBreakpoint`: Breakpoint size name.
 -   _operator_ `[WPViewportOperator]`: Viewport operator.
+-   _view_ `[Window]`: Window instance in which to perform viewport matching.
 
 _Returns_
 

diff --git a/...ompose/src/hooks/use-media-query/index.js → ...ompose/src/hooks/use-media-query/index.ts b/...ompose/src/hooks/use-media-query/index.js → ...ompose/src/hooks/use-media-query/index.ts
@@ -3,30 +3,38 @@
  */
 import { useMemo, useSyncExternalStore } from '@wordpress/element';
 
-const matchMediaCache = new Map();
+type MQLCache = Map< string, MediaQueryList >;
+
+const perWindowCache = new WeakMap< Window, MQLCache >();
 
 /**
  * A new MediaQueryList object for the media query
  *
- * @param {string} [query] Media Query.
- * @return {MediaQueryList|null} A new object for the media query
+ * @param view    Window.
+ * @param [query] Media Query.
  */
-function getMediaQueryList( query ) {
+function getMediaQueryList(
+	view: Window,
+	query?: string
+): MediaQueryList | null {
 	if ( ! query ) {
 		return null;
 	}
 
+	const matchMediaCache: MQLCache = perWindowCache.get( view ) ?? new Map();
+
+	if ( ! perWindowCache.has( view ) ) {
+		perWindowCache.set( view, matchMediaCache );
+	}
+
 	let match = matchMediaCache.get( query );
 
 	if ( match ) {
 		return match;
 	}
 
-	if (
-		typeof window !== 'undefined' &&
-		typeof window.matchMedia === 'function'
-	) {
-		match = window.matchMedia( query );
+	if ( typeof view?.matchMedia === 'function' ) {
+		match = view.matchMedia( query );
 		matchMediaCache.set( query, match );
 		return match;
 	}
@@ -37,16 +45,19 @@ function getMediaQueryList( query ) {
 /**
  * Runs a media query and returns its value when it changes.
  *
- * @param {string} [query] Media Query.
- * @return {boolean} return value of the media query.
+ * @param [query] Media Query.
+ * @param [view]  Window instance, else default to global window
+ * @return return value of the media query.
  */
-export default function useMediaQuery( query ) {
+export default function useMediaQuery(
+	query?: string,
+	view: Window = window
+): boolean {
 	const source = useMemo( () => {
-		const mediaQueryList = getMediaQueryList( query );
+		const mediaQueryList = getMediaQueryList( view, query );
 
 		return {
-			/** @type {(onStoreChange: () => void) => () => void} */
-			subscribe( onStoreChange ) {
+			subscribe( onStoreChange: any ) {
 				if ( ! mediaQueryList ) {
 					return () => {};
 				}
@@ -64,7 +75,7 @@ export default function useMediaQuery( query ) {
 				return mediaQueryList?.matches ?? false;
 			},
 		};
-	}, [ query ] );
+	}, [ view, query ] );
 
 	return useSyncExternalStore(
 		source.subscribe,

diff --git a/packages/compose/src/hooks/use-viewport-match/index.js b/packages/compose/src/hooks/use-viewport-match/index.js
@@ -64,6 +64,7 @@ ViewportMatchWidthContext.displayName = 'ViewportMatchWidthContext';
  *
  * @param {WPBreakpoint}       breakpoint      Breakpoint size name.
  * @param {WPViewportOperator} [operator=">="] Viewport operator.
+ * @param {Window}             [view=window]   Window instance in which to perform viewport matching.
  *
  * @example
  *
@@ -74,12 +75,12 @@ ViewportMatchWidthContext.displayName = 'ViewportMatchWidthContext';
  *
  * @return {boolean} Whether viewport matches query.
  */
-const useViewportMatch = ( breakpoint, operator = '>=' ) => {
+const useViewportMatch = ( breakpoint, operator = '>=', view = window ) => {
 	const simulatedWidth = useContext( ViewportMatchWidthContext );
 	const mediaQuery =
 		! simulatedWidth &&
 		`(${ CONDITIONS[ operator ] }: ${ BREAKPOINTS[ breakpoint ] }px)`;
-	const mediaQueryResult = useMediaQuery( mediaQuery || undefined );
+	const mediaQueryResult = useMediaQuery( mediaQuery || undefined, view );
 	if ( simulatedWidth ) {
 		return OPERATOR_EVALUATORS[ operator ](
 			BREAKPOINTS[ breakpoint ],

diff --git a/packages/compose/src/hooks/use-viewport-match/test/index.js b/packages/compose/src/hooks/use-viewport-match/test/index.js
@@ -44,15 +44,18 @@ describe( 'useViewportMatch', () => {
 		expect( useMediaQueryMock ).toHaveBeenCalledTimes( 3 );
 		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
 			1,
-			'(max-width: 1280px)'
+			'(max-width: 1280px)',
+			window
 		);
 		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
 			2,
-			'(min-width: 782px)'
+			'(min-width: 782px)',
+			window
 		);
 		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
 			3,
-			'(min-width: 600px)'
+			'(min-width: 600px)',
+			window
 		);
 	} );
 
@@ -76,15 +79,18 @@ describe( 'useViewportMatch', () => {
 		expect( useMediaQueryMock ).toHaveBeenCalledTimes( 3 );
 		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
 			1,
-			'(min-width: 1440px)'
+			'(min-width: 1440px)',
+			window
 		);
 		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
 			2,
-			'(max-width: 960px)'
+			'(max-width: 960px)',
+			window
 		);
 		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
 			3,
-			'(max-width: 480px)'
+			'(max-width: 480px)',
+			window
 		);
 	} );
 
@@ -121,9 +127,25 @@ describe( 'useViewportMatch', () => {
 
 		expect( useMediaQueryMock ).toHaveBeenCalledTimes( 4 );
 		// `useMediaQuery` is expected to receive `undefined` when simulating width.
-		expect( useMediaQueryMock ).toHaveBeenNthCalledWith( 1, undefined );
-		expect( useMediaQueryMock ).toHaveBeenNthCalledWith( 2, undefined );
-		expect( useMediaQueryMock ).toHaveBeenNthCalledWith( 3, undefined );
-		expect( useMediaQueryMock ).toHaveBeenNthCalledWith( 4, undefined );
+		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
+			1,
+			undefined,
+			window
+		);
+		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
+			2,
+			undefined,
+			window
+		);
+		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
+			3,
+			undefined,
+			window
+		);
+		expect( useMediaQueryMock ).toHaveBeenNthCalledWith(
+			4,
+			undefined,
+			window
+		);
 	} );
 } );