Media: Add umb-media-thumbnail with configurable checkerboard background (closes #23177) by iOvergaard · Pull Request #23178 · umbraco/Umbraco-CMS

iOvergaard · 2026-06-22T11:08:11Z

Prerequisites

I have added steps to test this contribution in the description below

If there's an existing issue for this PR then this fixes #23177

Description

From discussion #23177: the media thumbnail always renders transparent images over a checkerboard pattern. That's right when managing media (it signals transparency to an editor) but wrong when the thumbnail represents final content (block grid items, pickers feeding the front-end), where the image should sit on a transparent background. It's also the only turnkey component that does server-side cropping — umb-media-image respects transparency but can't crop — so people were dropping down to UmbImagingRepository by hand ("a lot of work just showing an image"). This closes that gap and gives the component a clearer, forward-looking name.

Changes

umb-media-thumbnail is the component (UmbMediaThumbnailElement). The name leaves room for non-media thumbnails in future (per review).
Configurable background — the checkerboard is driven by the --umb-media-thumbnail-background CSS custom property (default unchanged). Set it to none for a transparent background; it inherits, so it can be set on any ancestor.
img part — the underlying <img> is exposed as part="img" for full styling control (object-fit, border-radius, …).
umb-imaging-thumbnail is kept as a thin alias of umb-media-thumbnail — both tags are supported for now. It keeps a @deprecated JSDoc marker (so IDEs steer you to the new name) but emits no runtime warning.
Internal consumers migrated to umb-media-thumbnail (media collection card, media picker, input-media, input-rich-media).
Listener-leak fix — #observeActionEvent added an UmbEntityUpdatedEvent listener to the app-level action-event context and never removed it; now cleaned up on disconnect (following the media-workspace.context.ts pattern).
Docs & tests — a Storybook story (Entity/Media/Components/Media Thumbnail), an MDX guide (Guides/Working with Media Images), and component tests covering the part, the --umb-media-thumbnail-background opt-out, and the alias relationship.

How to test

cd src/Umbraco.Web.UI.Client && npm test -- --files "src/packages/media/imaging/**/*.test.ts" — green; npm run check:circular reports no cycles.
npm run storybook → Entity/Media/Components/Media Thumbnail: Default shows the checkerboard behind a transparent image; Transparent Background (--umb-media-thumbnail-background: none) shows it on a solid colour with no checkerboard.
In a running backoffice, the Media section / media pickers render thumbnails exactly as before (default behaviour unchanged); <umb-imaging-thumbnail> still works as an alias.

Fixes #23177

🤖 Generated with Claude Code

Adds `umb-thumbnail` as the recommended alias of `umb-imaging-thumbnail` (the original tag stays registered for backwards compatibility), and makes the checkerboard background opt-out via the `--umb-thumbnail-background` CSS custom property plus an `img` part for full styling control. Also fixes an action-event listener leak in the thumbnail element, and adds a Storybook story, an MDX guide, and component tests. Closes #23177 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

claude · 2026-06-22T11:08:28Z

Claude finished @iOvergaard's task in 6m 9s —— View job

PR Review

Target: origin/v17/dev · Based on commit: e82df5d22b7993d5289fb6ed7c1c2ab5e11e08f7

Adds umb-thumbnail as the recommended alias for umb-imaging-thumbnail, introduces --umb-thumbnail-background for configurable checkerboard/transparent backgrounds, exposes part="img" for CSS styling, and fixes a listener leak in the action-event observer.

Modified public API: UmbImagingThumbnailElement — added part="img" and --umb-thumbnail-background CSS custom property (default behaviour unchanged)
Other changes: New exported UmbThumbnailElement / umb-thumbnail custom element; umb-imaging-thumbnail kept as a permanent alias (no deprecation schedule in this PR)

Suggestions

imaging-thumbnail.element.ts:14: JSDoc says "Prefer the umb-thumbnail alias" without @deprecated. If umb-imaging-thumbnail is on track for eventual removal, add a @deprecated JSDoc tag now for IDE warnings, even without the runtime UmbDeprecation noise. If it's a permanent alias, rephrasing is cleaner so the recommendation signal lives only on umb-thumbnail.
imaging-thumbnail.element.test.ts:22: _thumbnailUrl is accessed via as unknown as { _thumbnailUrl: string }. If the field is renamed, the test compiles fine but silently injects nothing, making the assertions vacuous. A guard assertion expect(element.shadowRoot!.querySelector('#figure')).to.not.equal(null) early in beforeEach would catch a broken setup loudly. (Same pattern in thumbnail.element.test.ts:23.)

Approved with Suggestions for improvement

The listener-leak fix is correct — the arrow-function class field keeps a stable reference so removeEventListener reliably undoes the matching addEventListener, and disconnectedCallback cleans up before any re-mount. The CSS var() fallback is a clean pattern that leaves the default unchanged. Good work closing the gap between umb-imaging-thumbnail and umb-media-image that was forcing consumers to drop down to UmbImagingRepository directly.

Copilot

Pull request overview

This PR improves Umbraco’s backoffice imaging UX by introducing a recommended umb-thumbnail alias for the existing umb-imaging-thumbnail, while making the checkerboard transparency background configurable via a CSS custom property and exposing the internal <img> for styling.

Changes:

Added umb-thumbnail as an alias of umb-imaging-thumbnail and exported it from the imaging components index.
Made the checkerboard background configurable via --umb-thumbnail-background (default unchanged) and exposed the rendered <img> as part="img".
Fixed an action-event listener leak by ensuring the UmbEntityUpdatedEvent listener is removed on disconnect; added Storybook docs/stories and component tests.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/Umbraco.Web.UI.Client/src/packages/media/imaging/stories/working-with-media-images.mdx	Adds a guide describing when to use `umb-thumbnail`/`umb-media-image`, and how to disable the checkerboard / style the `img` part.
src/Umbraco.Web.UI.Client/src/packages/media/imaging/components/thumbnail.stories.ts	Adds Storybook stories for default checkerboard, transparent background override, and fallback icon behavior.
src/Umbraco.Web.UI.Client/src/packages/media/imaging/components/thumbnail.element.ts	Registers `umb-thumbnail` as the recommended alias for the imaging thumbnail element with JSDoc for cssprop/csspart.
src/Umbraco.Web.UI.Client/src/packages/media/imaging/components/thumbnail.element.test.ts	Adds tests covering aliasing, `part="img"`, default checkerboard, and background override behavior for `umb-thumbnail`.
src/Umbraco.Web.UI.Client/src/packages/media/imaging/components/index.ts	Exports the new `thumbnail.element.js` from the imaging components barrel.
src/Umbraco.Web.UI.Client/src/packages/media/imaging/components/imaging-thumbnail.element.ts	Adds `part="img"`, introduces `--umb-thumbnail-background`, and fixes action-event listener cleanup on disconnect.
src/Umbraco.Web.UI.Client/src/packages/media/imaging/components/imaging-thumbnail.element.test.ts	Adds tests covering `part="img"` and `--umb-thumbnail-background` behavior for `umb-imaging-thumbnail`.

- Rephrase the imaging-thumbnail JSDoc to a neutral alias statement instead of a "prefer" wording that read like an undeclared deprecation. - Guard the thumbnail tests so a renamed private field fails loudly rather than producing vacuous assertions. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

iOvergaard · 2026-06-22T15:09:46Z

Thanks for the review — both addressed in 3165423:

JSDoc wording — umb-imaging-thumbnail is a permanent backwards-compat alias (no removal scheduled), so I dropped the "prefer" phrasing that read like an undeclared deprecation and made it a neutral statement of the alias relationship. The "recommended" signal now lives on umb-thumbnail's own JSDoc.
Test fragility — added a guard in beforeEach (#figure must render) to both test files, so if the private _thumbnailUrl field is ever renamed the setup fails loudly instead of leaving the assertions vacuous.

Note for context: migrating the four internal umb-imaging-thumbnail usages to umb-thumbnail is intentionally a follow-up PR.

…thumbnail Invert the inheritance so the implementation lives on `UmbThumbnailElement` (`umb-thumbnail`) and `UmbImagingThumbnailElement` (`umb-imaging-thumbnail`) is the thin subclass. Removing the old tag is now just deleting one file. The deprecated subclass emits a one-time `UmbDeprecation` warning (a module-level guard avoids per-instance console spam) and carries a `@deprecated` JSDoc, scheduled for removal in Umbraco 19. Migrate the four internal consumers to `umb-thumbnail` so the deprecation warning targets external code only, not our own. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-23T08:02:37Z

Azure Static Web Apps: Your stage site is ready! Visit it here: https://orange-sea-0c7411a03-23178.westeurope.6.azurestaticapps.net

…guard The img part, checkerboard default and --umb-thumbnail-background override are covered by thumbnail.element.test.ts and inherited from UmbThumbnailElement, so re-asserting them on the umb-imaging-thumbnail subclass only tested inheritance. Keep a single backwards-compat guard that the deprecated alias stays registered and on the inheritance chain. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-06-23T09:18:42Z

Azure Static Web Apps: Your stage site is ready! Visit it here: https://orange-sea-0c7411a03-23178.westeurope.6.azurestaticapps.net

@deprecated

…lias keeps @deprecated, no runtime warning Per review (Niels): the forward-looking name is `umb-media-thumbnail` (`UmbMediaThumbnailElement`), leaving room for non-media thumbnails later. The implementation, CSS custom property (`--umb-media-thumbnail-background`), story, guide and internal consumers all use the new name. `umb-imaging-thumbnail` stays registered as a thin alias and keeps its `@deprecated` JSDoc (IDE signal) but no longer emits a runtime UmbDeprecation warning — both tags fly for now. Docs and comments lead with umb-media-thumbnail. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

iOvergaard · 2026-06-24T08:59:06Z

Updated per the review:

Renamed the component to umb-media-thumbnail (UmbMediaThumbnailElement) — leaves room for non-media thumbnails later. The CSS custom property (--umb-media-thumbnail-background), img part, story, guide and the four internal consumers all use the new name.
umb-imaging-thumbnail stays as a thin alias — both tags supported for now. It keeps the @deprecated JSDoc marker (IDE steer) but no runtime UmbDeprecation warning, so no console noise.
Docs and comments lead with umb-media-thumbnail only.

Tests green, no circular deps, lint clean (bar the expected self-deprecation notice on the alias's own tag-map entry).

github-actions · 2026-06-24T09:01:05Z

Azure Static Web Apps: Your stage site is ready! Visit it here: https://orange-sea-0c7411a03-23178.westeurope.6.azurestaticapps.net

Copilot AI review requested due to automatic review settings June 22, 2026 11:08

Copilot started reviewing on behalf of iOvergaard June 22, 2026 11:08 View session

Copilot AI reviewed Jun 22, 2026

View reviewed changes

claude Bot reviewed Jun 22, 2026

View reviewed changes

Comment thread src/Umbraco.Web.UI.Client/src/packages/media/imaging/components/imaging-thumbnail.element.ts

claude Bot reviewed Jun 22, 2026

View reviewed changes

Comment thread ...mbraco.Web.UI.Client/src/packages/media/imaging/components/imaging-thumbnail.element.test.ts

claude Bot added area/frontend category/ux User experience category/ui User interface labels Jun 22, 2026

bjarnef reviewed Jun 22, 2026

View reviewed changes

Comment thread ...mbraco.Web.UI.Client/src/packages/media/imaging/components/imaging-thumbnail.element.test.ts Outdated

nielslyngsoe reviewed Jun 23, 2026

View reviewed changes

Comment thread src/Umbraco.Web.UI.Client/src/packages/media/imaging/components/imaging-thumbnail.element.ts Outdated

iOvergaard added the preview/storybook Pull requests that can be previewed through Storybook label Jun 23, 2026

iOvergaard changed the title ~~Imaging: Add umb-thumbnail with configurable checkerboard background (closes #23177)~~ Media: Add umb-media-thumbnail with configurable checkerboard background (closes #23177) Jun 24, 2026

nielslyngsoe approved these changes Jun 24, 2026

View reviewed changes

nielslyngsoe enabled auto-merge (squash) June 24, 2026 09:13

iOvergaard added release/18.1.0 release/17.6.0 type/feature labels Jun 24, 2026

nielslyngsoe merged commit 065e567 into v17/dev Jun 24, 2026
30 checks passed

nielslyngsoe deleted the v17/feature/23177-imaging-thumbnail-transparent-background branch June 24, 2026 09:37

iOvergaard mentioned this pull request Jun 24, 2026

Backoffice: Add Working with Media documentation (17.6 & 18.1) umbraco/UmbracoDocs#8187

Merged

8 tasks

dependabot Bot mentioned this pull request Aug 14, 2026

Bump the dotnet-minor-patch-deps group with 13 updates MiguelGuedelha/MiguelGuedelha.Umbraco.Templates#76

Merged

Navigation Menu

Uh oh!

Media: Add umb-media-thumbnail with configurable checkerboard background (closes #23177) - #23178

Media: Add umb-media-thumbnail with configurable checkerboard background (closes #23177)#23178
nielslyngsoe merged 5 commits into
v17/devfrom
v17/feature/23177-imaging-thumbnail-transparent-background

iOvergaard commented Jun 22, 2026 •

edited

Loading

Uh oh!

claude Bot commented Jun 22, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

iOvergaard commented Jun 22, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 23, 2026

Uh oh!

github-actions Bot commented Jun 23, 2026

Uh oh!

iOvergaard commented Jun 24, 2026

Uh oh!

github-actions Bot commented Jun 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

iOvergaard commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Prerequisites

Description

Uh oh!

claude Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review

Suggestions

Approved with Suggestions for improvement

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

iOvergaard commented Jun 22, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 23, 2026

Uh oh!

github-actions Bot commented Jun 23, 2026

Uh oh!

iOvergaard commented Jun 24, 2026

Uh oh!

github-actions Bot commented Jun 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

iOvergaard commented Jun 22, 2026 •

edited

Loading

claude Bot commented Jun 22, 2026 •

edited

Loading