[ciampo]

See #84537, Batch 1.

What?

Use the WordPress UI Avatar in the post, template, template-part, and media author fields.

Why?

These fields duplicate image-loading state and avatar styles. The shared Avatar handles loaded, missing, and failed author images with initials as the fallback.

How?

Render the 16px Avatar whenever an author image URL or initials are available. Show the image when it loads; otherwise show up to two initials; otherwise show the original author icon without an Avatar frame. Avatar owns image loading and failure states. Theme authors retain their original icon and spacing. Preserve author lookup, visible names, and site/plugin fallbacks. Avatars remain decorative beside the author field.

Testing Instructions

1. In the Site Editor's Pages view, show the Author field and confirm images and names render together.
2. Change a post's author in the editor and confirm the displayed name and image or initials update.
3. In Templates and Template Parts, show the Author field. Check user and site images, initials for users without a working image, the plugin fallback icon, and the original standalone theme icon. Repeat in the extensible Site Editor.
4. In Storybook's Media Fields → Data Views Preview, check the Author column. Reload to check cached images.
5. Block an author image request in browser DevTools and reload. Confirm initials remain visible beside the name. Block a site-logo request and confirm its source icon remains visible. Check a narrow column with a long name.
6. Open the post editor's revision timeline with named and unnamed authors. Confirm the available images load. Named authors use initials when their image is unavailable; unnamed authors use the original standalone icon.
7. In the author response, retain avatar_urls[48] and clear name or replace it with whitespace. For template users, also clear author_text. Confirm the image still displays. Make the image request fail and confirm the original icon appears without an Avatar frame.

Testing Instructions for Keyboard

Use Tab to reach the post's Author control and change the selection with the keyboard. Confirm the name and avatar update, and the avatar adds no tab stop.

Screenshots

Captured in a disposable WordPress Playground site with Twenty Twenty-Five and demo data. Each pair uses a 1440 × 1000 viewport, the same view and data, and a fixed browser clock. Images are cropped to the affected interface. Before is 47d76d8364e; after is f89677e8a5a. After captures wait for visible images to finish loading and displaying. The Pages and media picker examples include loaded, missing, and failed avatar images; the revision timeline includes an unnamed author.

Site Editor

Pages

Before	After

Templates

Before	After

Template Parts

Before	After

Extensible Site Editor

Pages

Before	After

Templates

Before	After

Template Parts

Before	After

Post editor

Post inspector with DataForm enabled

Before	After

Revision timeline

Recaptured after the Gravatar image loaded successfully in both builds. The missing-image row shows the fallback.

Before	After

Media

Media picker with DataViews enabled

Before	After

Media Editor details

Before	After

Initials at all sizes

Isolated composition of the compiled Avatar with its native initials fallback in all five sizes and both shapes. The 16px avatar uses the component's default 8px initials.

Image priority with missing or blank names

Matched fixture using the compiled post, template-user, and media author renderers with production styles and the same demo inputs. Before is 09651df8820; after is f89677e8a5a. Valid images use the demo SVG portrait. Failed requests return an actual 404.

Before	After

Verification

• Production build, affected-package typecheck, JavaScript and CSS lint, and changelog validation passed.
• Browser inspection verified image priority with missing and blank names in all three author renderers, initials for named image failures, unframed original icons for unnamed failures, and switching from a loaded image to a failed URL and back. Both Site Editors retain standalone theme icons. The revision Gravatar finished loading and displayed before capture.
• Existing unit assertions were updated for initials. No new tests were added and unit tests were not rerun for this change, as requested.
• Avatar is currently marked use-with-caution. These packages already bundle @wordpress/ui; the imports include the same explicit lint exemption used by other bundled consumers.

Use of AI Tools

Implemented and verified with OpenAI Codex.

[github-actions]

🤖 PR meta 🤖

📦 Bundle size

Size Change: +5.78 kB (+0.07%)

Total Size: 8.52 MB

📦 View Changed

Filename	Size	Change
build/scripts/editor/index.min.js	639 kB	+2.89 kB (+0.45%)
build/scripts/media-utils/index.min.js	231 kB	+2.9 kB (+1.27%)
build/styles/edit-site/style-rtl.css	21.9 kB	-6 B (-0.03%)
build/styles/edit-site/style-rtl.min.css	17.9 kB	-3 B (-0.02%)
build/styles/edit-site/style.css	21.9 kB	-4 B (-0.02%)
build/styles/edit-site/style.min.css	17.8 kB	-4 B (-0.02%)
build/styles/editor/style-rtl.css	32.6 kB	-14 B (-0.04%)
build/styles/editor/style-rtl.min.css	27.7 kB	-4 B (-0.01%)
build/styles/editor/style.css	32.7 kB	-15 B (-0.05%)
build/styles/editor/style.min.css	27.7 kB	-4 B (-0.01%)
build/styles/media-utils/style-rtl.css	3.46 kB	+9 B (+0.26%)
build/styles/media-utils/style-rtl.min.css	2.4 kB	+15 B (+0.63%)
build/styles/media-utils/style.css	3.48 kB	+10 B (+0.29%)
build/styles/media-utils/style.min.css	2.4 kB	+14 B (+0.59%)

_{f89677e Run}

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric	1d4f175	trunk	% Change
timeToFirstByte	54.7 ms +12.61% -3.56%	53.4 ms +9.46% -1.59%	2.43%
largestContentfulPaint	94 ms +2.13% -6.38%	96 ms +2.08% -8.33%	-2.08%
lcpMinusTtfb	35 ms +12.29% -4.29%	39.3 ms +9.54% -14.12%	-10.94%
wpBeforeTemplate	28.96 ms +14.61% -2.24%	28.24 ms +7.83% -0.42%	2.55%
wpTemplate	21.17 ms +4.68% -3.02%	21.07 ms +5.03% -2.99%	0.47%
wpTotal	51.01 ms +12.17% -3.63%	49.7 ms +8.81% -1.61%	2.64%
wpMemoryUsage	7.61 MB +0% -0%	7.58 MB +0% -0%	0.46%
wpDbQueries	17 +0% -0%	17 +0% -0%	0%

front-end-classic-theme

Metric	1d4f175	trunk	% Change
timeToFirstByte	45.55 ms +11.86% -1.87%	46.55 ms +7.73% -2.69%	-2.15%
largestContentfulPaint	100 ms +6% -0%	100 ms +4% -0%	0%
lcpMinusTtfb	54.8 ms +1% -2.74%	54.7 ms +1.28% -1.55%	0.18%
wpBeforeTemplate	26.49 ms +11.06% -1.74%	26.33 ms +14.74% -1.71%	0.61%
wpTemplate	15.98 ms +2.94% -1.5%	16.15 ms +5.14% -0.99%	-1.05%
wpTotal	42.54 ms +11.89% -1.69%	43.61 ms +6.97% -3.3%	-2.45%
wpMemoryUsage	6.25 MB +0% -0%	6.20 MB +0% -0%	0.71%
wpDbQueries	14 +0% -0%	14 +0% -0%	0%

media-processing

Metric	1d4f175	trunk	% Change
mediaProcessingJpeg	401.24 ms +0.36% -0.34%	397.56 ms +0.64% -0.79%	0.93%
mediaProcessingAvif	6036.07 ms +0.17% -0.09%	6044.31 ms +0.25% -0.27%	-0.14%
mediaProcessingJpegToAvif	4153.48 ms +0.2% -0.23%	4172.82 ms +0.6% -0.38%	-0.46%

media-upload

Metric	1d4f175	trunk	% Change
jpegUploadProcessing	1437.02 ms +34.92% -0.89%	1424.81 ms +0.78% -0.45%	0.86%
pngUploadProcessing	214.89 ms +3.08% -14.02%	209.53 ms +7.53% -13.68%	2.56%
largeJpegUploadProcessing	1400.46 ms +1.5% -0.4%	1415.15 ms +0.22% -0.68%	-1.04%
multipleImageUploadProcessing	1555.47 ms +1.13% -2.09%	1566.16 ms +1.68% -1.13%	-0.68%

post-editor

Metric	1d4f175	trunk	% Change
serverResponse	248.65 ms +10.33% -5.26%	261.06 ms +1.67% -9.74%	-4.75%
firstPaint	149.53 ms +11.19% -4.16%	154.68 ms +21.63% -15.01%	-3.33%
domContentLoaded	713.37 ms +4.74% -3.09%	688.37 ms +2.83% -3.86%	3.63%
loaded	714.34 ms +4.74% -3.1%	689.24 ms +2.83% -3.85%	3.64%
firstContentfulPaint	322.57 ms +4.63% -2.74%	308.65 ms +5.67% -5.62%	4.51%
firstBlock	2005.56 ms +2.33% -1.54%	1975.48 ms +1.8% -1.47%	1.52%
type	13.36 ms +2.84% -1.95%	13.57 ms +2.06% -1.11%	-1.55%
typeWithoutInspector	13.93 ms +4.74% -5.03%	14.02 ms +14.55% -7.13%	-0.64%
typeWithTopToolbar	16.55 ms +2.84% -3.75%	17.73 ms +7.5% -6.43%	-6.66%
typeContainer	6.37 ms +2.04% -8.63%	6.09 ms +7.88% -2.79%	4.6%
focus	72.29 ms +4.5% -3.71%	68.17 ms +5.47% -3.4%	6.04%
firstFocus	131.14 ms +0% -0%	141.74 ms +0% -0%	-7.48%
selectAll	328.11 ms +1.55% -0.92%	332.47 ms +9.2% -2.03%	-1.31%
listViewOpen	43.71 ms +8.67% -5.65%	45.14 ms +11.54% -8.99%	-3.17%
inserterOpen	25.05 ms +2.44% -3.07%	25.64 ms +6.08% -3.51%	-2.3%
inserterHover	8.63 ms +3.36% -3.59%	8.74 ms +9.73% -5.61%	-1.26%
inserterSearch	6.35 ms +8.03% -5.2%	6.26 ms +5.27% -6.71%	1.44%
loadPatterns	421.68 ms +1.01% -1.37%	435.19 ms +2.29% -6.17%	-3.1%
wpTotal	241.06 ms +10.64% -5.47%	253.31 ms +1.67% -10%	-4.84%
wpMemoryUsage	13.33 MB +0% -0%	13.30 MB +0% -0%	0.28%
wpDbQueries	54 +0% -0%	54 +0% -0%	0%

site-editor

Metric	1d4f175	trunk	% Change
serverResponse	499.67 ms +5.94% -1.94%	490.6 ms +4.79% -4.47%	1.85%
firstPaint	266.19 ms +23.8% -7.73%	228.34 ms +27.02% -5.64%	16.58%
domContentLoaded	1281.41 ms +1% -1.4%	1236.72 ms +2.73% -0.67%	3.61%
loaded	1282.71 ms +1.01% -1.41%	1237.86 ms +2.75% -0.65%	3.62%
firstContentfulPaint	511.2 ms +1.28% -0.99%	490.62 ms +2.91% -4.43%	4.19%
firstBlock	4732.38 ms +0.44% -0.55%	4711.54 ms +0.65% -1.47%	0.44%
type	19.33 ms +6.41% -2.17%	19.48 ms +5.6% -1.54%	-0.77%
navigate	140.51 ms +8.89% -9.53%	130.42 ms +12.02% -0.72%	7.74%
loadPatterns	1370.24 ms +9.12% -4.38%	1349.91 ms +5.14% -8.8%	1.51%
loadPages	1047.31 ms +2.94% -1.28%	1060.36 ms +6.3% -3.12%	-1.23%
wpTotal	488.76 ms +5.94% -1.92%	479.61 ms +4.91% -4.59%	1.91%
wpMemoryUsage	12.38 MB +0% -0%	12.34 MB +0% -0%	0.3%
wpDbQueries	43 +2.33% -0%	43 +2.33% -0%	0%

_{f89677e Run}

[ciampo]

@WordPress/gutenberg-components @WordPress/gutenberg-design

As I started to swap the existing "avatar"-like UI with the new Avatar component, I realized that there is one main visual mismatch: when there isn't a user profile image, we currently fall back to the commentAuthorAvatar icon

This icon doesn't quite work well with Avatar because it has an embedded border:

• it can't be displayed by the Avatar component because it would result in a nested double border
• the border itself is darker and thicker than Avatar's, which introduces inconsistencies

As a consequence, in order to preserve existing behavior, we'd need to introduce exceptions to Avatar so that it displays that icon as a fallback if the main image fails to load (or can't be found) AND no initials are provided.

But IMO this is a chance to discuss broader avatar designs. My proposal is to:

• stop using commentAuthorAvatar as a fallback for when there's no avatar to display;
• prepare a new fallback icon for the Avatar component; the icon shouldn't have an embedded border and should look good when rendered inside Avatar (at all sizes and shapes);
• Show this new fallback icon only if the main image can't load AND there are no fallback initials;
• we can continue using the commentAuthorAvatar icon when we generally need a decorative icon for a generic "user avatar", and not for specific ones

[Mamaduka]

+1 to good fallback icon. As @ciampo mentioned, the commentAuthorAvatar isn't flexible for every design.

I also don't like using the __experimentalDiscussionSettings.avatarURL setting everywhere. Not every profile image should use the discussion fallback avatar.

[jameskoster]

Does it need to be an icon? Perhaps we could display a diagonal line, similar to the unset color swatch:

[ciampo]

It doesn't have to be an icon — in fact, Base UI (and our @wordpress/ui version) both use initials as fallback.

So maybe we can use initials and, if for any reason that can't be done, fall back to the diagonal line?

Also, @jameskoster , while we're here, do you think that Avatar should keep its thin neutral border? Asking because there are situations where the preivious icon, with its thick border, looked a lot more "balanced" next to other icons with the same thick border, example:

[jameskoster]

Yes Avatar should keep it's border weight, but I think we should reduce the size of the status icons so they blend better with the text. Similar to input validation messages:

That would reduce stroke width so they align better with Avatar as well.