Font library: Add skeleton loader for the font preview images

packages/global-styles-ui/CHANGELOG.md

@@ -9,6 +9,7 @@
 ### Enhancements
 
 -   Add a `showBlockStateControls` prop to `GlobalStylesUI`, defaulting to `true`, which hides the state controls for blocks when set to `false` ([#80956](https://github.com/WordPress/gutenberg/pull/80956)).
+-   Font Library: Add a skeleton loader for the font preview images ([#81047](https://github.com/WordPress/gutenberg/pull/81047)).
 
 ## 1.19.0 (2026-07-29)
 

packages/global-styles-ui/src/font-library/font-demo.tsx

@@ -1,13 +1,18 @@
-import { __experimentalText as WCText } from '@wordpress/components';
+import clsx from 'clsx';
 import { useContext, useEffect, useState, useRef } from '@wordpress/element';
 import type { FontFamily, FontFace } from '@wordpress/core-data';
+import { Text, Skeleton } from '@wordpress/ui';
 import { FontLibraryContext } from './context';
 import {
 	getFacePreviewStyle,
 	getFamilyPreviewStyle,
 } from './utils/preview-styles';
 import type { FontDemoProps } from './types';
 
+// Previews already loaded this session, so reopening the library doesn't flash
+// a placeholder for images the browser already has.
+const loadedPreviews = new Set< string >();
+
 function getPreviewUrl( fontFace: FontFace ): string | undefined {
 	if ( fontFace.preview ) {
 		return fontFace.preview;
@@ -47,19 +52,29 @@ function getDisplayFontFace( font: FontFamily | FontFace ): FontFace {
 
 function FontDemo( { font, text }: FontDemoProps ) {
 	const ref = useRef< HTMLDivElement >( null );
+	const imgRef = useRef< HTMLImageElement >( null );
 
 	const fontFace = getDisplayFontFace( font );
 	const style = getFamilyPreviewStyle( font );
 	text = text || ( 'name' in font ? font.name : '' );
 	const customPreviewUrl = font.preview;
 
+	const previewUrl = customPreviewUrl ?? getPreviewUrl( fontFace );
+	const isPreviewImage = Boolean(
+		previewUrl && /\.(png|jpg|jpeg|gif|svg)$/i.test( previewUrl )
+	);
+
 	const [ isIntersecting, setIsIntersecting ] = useState< boolean >( false );
-	const [ isAssetLoaded, setIsAssetLoaded ] = useState< boolean >( false );
+	const [ isAssetLoaded, setIsAssetLoaded ] = useState< boolean >(
+		() => !! previewUrl && loadedPreviews.has( previewUrl )
+	);
 	const { loadFontFaceAsset } = useContext( FontLibraryContext );
 
-	const previewUrl = customPreviewUrl ?? getPreviewUrl( fontFace );
-	const isPreviewImage =
-		previewUrl && previewUrl.match( /\.(png|jpg|jpeg|gif|svg)$/i );
+	// The previews scale with the label, so estimate ~12px per character.
+	const estimatedImageWidth = Math.min(
+		Math.max( text.length * 12, 48 ),
+		300
+	);
 
 	const faceStyles = getFacePreviewStyle( fontFace );
 	const textDemoStyle = {
@@ -71,19 +86,33 @@ function FontDemo( { font, text }: FontDemoProps ) {
 	};
 
 	useEffect( () => {
+		// Only font files need the viewport check. Image previews are lazy
+		// loaded by the browser, and every row in the collection has one.
+		if ( isPreviewImage ) {
+			return;
+		}
 		const observer = new window.IntersectionObserver( ( [ entry ] ) => {
 			setIsIntersecting( entry.isIntersecting );
 		}, {} );
 		if ( ref.current ) {
 			observer.observe( ref.current );
 		}
 		return () => observer.disconnect();
-	}, [ ref ] );
+	}, [ isPreviewImage ] );
+
+	// Re-check on preview change, since an already complete image won't fire
+	// onLoad and the component is reused across fonts.
+	useEffect( () => {
+		setIsAssetLoaded(
+			( !! previewUrl && loadedPreviews.has( previewUrl ) ) ||
+				!! imgRef.current?.complete
+		);
+	}, [ previewUrl ] );
 
 	useEffect( () => {
 		const loadAsset = async () => {
-			if ( isIntersecting ) {
-				if ( ! isPreviewImage && fontFace.src ) {
+			if ( isIntersecting && ! isPreviewImage ) {
+				if ( fontFace.src ) {
 					await loadFontFaceAsset( fontFace );
 				}
 				setIsAssetLoaded( true );
@@ -93,21 +122,41 @@ function FontDemo( { font, text }: FontDemoProps ) {
 	}, [ fontFace, isIntersecting, loadFontFaceAsset, isPreviewImage ] );
 
 	return (
-		<div ref={ ref }>
+		<div ref={ ref } className="font-library__font-demo">
 			{ isPreviewImage ? (
-				<img
-					src={ previewUrl }
-					loading="lazy"
-					alt={ text }
-					className="font-library__font-variant_demo-image"
-				/>
+				<>
+					{ ! isAssetLoaded && (
+						<Skeleton
+							className="font-library__font-variant-demo-skeleton"
+							style={ { width: estimatedImageWidth } }
+						/>
+					) }
+					<img
+						ref={ imgRef }
+						src={ previewUrl }
+						loading="lazy"
+						alt={ text }
+						onLoad={ () => {
+							if ( previewUrl ) {
+								loadedPreviews.add( previewUrl );
+							}
+							setIsAssetLoaded( true );
+						} }
+						// Also on failure, otherwise skeleton will pulse forever.
+						onError={ () => setIsAssetLoaded( true ) }
+						className={ clsx(
+							'font-library__font-variant_demo-image',
+							{ 'is-loading': ! isAssetLoaded }
+						) }
+					/>
+				</>
 			) : (
-				<WCText
+				<Text
 					style={ textDemoStyle }
 					className="font-library__font-variant_demo-text"
 				>
 					{ text }
-				</WCText>
+				</Text>
 			) }
 		</div>
 	);

packages/global-styles-ui/src/font-library/style.scss

@@ -116,6 +116,11 @@ $footer-height: 90px;
 	margin-bottom: 0;
 }
 
+.font-library__font-demo {
+	// Anchors the image while it's out of flow during loading.
+	position: relative;
+}
+
 .font-library__font-card {
 	box-sizing: border-box;
 	border: variables.$border-width solid colors.$gray-300;
@@ -148,6 +153,26 @@ $footer-height: 90px;
 		display: block;
 		height: variables.$grid-unit-30;
 		width: auto;
+
+		@media not (prefers-reduced-motion) {
+			transition:
+				opacity var(--wpds-motion-duration-lg)
+				var(--wpds-motion-easing-subtle);
+		}
+
+		// Hidden while loading, but still rendered, since `display: none`
+		// would stop the lazy image from loading.
+		&.is-loading {
+			position: absolute;
+			top: 0;
+			left: 0;
+			opacity: 0;
+		}
+	}
+
+	.font-library__font-variant-demo-skeleton {
+		height: variables.$grid-unit-30;
+		border-radius: var(--wpds-border-radius-sm);
 	}
 
 	.font-library__font-variant_demo-text {

tools/eslint/suppressions.json

@@ -1568,11 +1568,6 @@
 			"count": 6
 		}
 	},
-	"packages/global-styles-ui/src/font-library/font-demo.tsx": {
-		"@wordpress/use-recommended-components": {
-			"count": 1
-		}
-	},
 	"packages/global-styles-ui/src/font-library/google-fonts-confirm-dialog.tsx": {
 		"@wordpress/use-recommended-components": {
 			"count": 5