feat: rework photo-viewer/asset-viewer - introduce adaptive-image.svelte by midzelis · Pull Request #25234 · immich-app/immich

midzelis · 2026-01-13T03:45:14Z

Large rework photo-viewer/asset-viewer

Instead of spinner, use a new adaptive-image component. This component will display the thumbhash as the base layer - quickly followed up by the (highly likely) pre-cached low-res thumbnail, and then kick off the preview-size thumbnail. Mouse-wheel zoom is supported using all formats: thumbhash, preview. Zoom will automatically 'upgrade' the preview thumbnail to be 'fullsize' (or original) on zoom, like before, but now there will be no flicker when the full quality one loads.

All next/previous thumbnails are eagerly pre-loaded, and all pending images are canceled if navigation occurs before they finish loading. Preloads are lower priority, and will back off if a main-image is being loaded.

github-actions · 2026-01-13T03:45:50Z

Preview environment has been removed.

alextran1502 · 2026-01-13T04:14:32Z

When I stop at an asset, wait a few seconds and navigate to the next. I'd expect the full preview image is loaded right away, but instead I am still seeing the thumbhash flash in

web/src/lib/actions/image-loader.svelte.ts

danieldietzler · 2026-02-05T11:24:39Z

web/src/lib/actions/image-loader.svelte.ts

+  if (params.alt !== undefined) {
+    img.alt = params.alt;
+  }
+  if (params.draggable !== undefined) {
+    img.draggable = params.draggable;
+  }
+  if (params.imgClass) {
+    img.className = classValueToString(params.imgClass);
+  }
+  if (params.role) {
+    img.role = params.role;
+  }
+  if (params.style !== undefined) {
+    img.setAttribute('style', params.style);
+  }
+  if (params.title !== undefined && params.title !== null) {
+    img.title = params.title;
+  }
+  if (params.loading !== undefined) {
+    img.loading = params.loading;
+  }


Is this just an Object.assign(img, params)?

I reworked image-loader -

const createImageElement = ( src: string | undefined, properties: ImageLoaderProperties, onLoad: () => void, onError: () => void, onStart?: () => void, ) => { if (!src) { return undefined; } const img = document.createElement('img'); if (properties.alt !== undefined) { img.alt = properties.alt; } if (properties.draggable !== undefined) { img.draggable = properties.draggable; } if (properties.loading !== undefined) { img.loading = properties.loading; } img.addEventListener('load', onLoad); img.addEventListener('error', onError); onStart?.(); img.src = src; return img; };

there are only 3 props now. Also - I can't really use object.assign, since that will assign 'undefined' to properties like img.alt which assigned the STRING 'undefined' to alt. I think this is cleanest for now.

To be clear, what I meant is Object.assign(img, properties)

web/src/lib/actions/image-loader.svelte.ts

web/src/lib/components/asset-viewer/adaptive-image.svelte

web/src/lib/components/asset-viewer/detail-panel.svelte

web/src/lib/components/asset-viewer/photo-viewer.svelte

web/src/lib/components/assets/thumbnail/image-thumbnail.svelte

web/src/lib/components/assets/thumbnail/thumbnail.svelte

web/src/lib/components/asset-viewer/photo-viewer.svelte

michelheusschen · 2026-02-16T09:02:06Z

web/src/lib/components/AdaptiveImage.svelte

+  let previousAssetId: string | undefined;
+  let previousSharedLinkId: string | undefined;
+
+  const adaptiveImageLoader = $derived.by(() => {


You should not assign state inside a $derived please change this to an $effect

I looked into converting this to $effect and it doesn't work cleanly here. The core issue is timing: $derived.by evaluates synchronously before the template renders, so adaptiveImageLoader is always available. $effect runs after the render cycle, which means the loader would be undefined for the first frame (and on every asset change).

This matters because adaptiveImageLoader in the template. Converting to $effect would require ?. null guards at ~20 places. So, the code becomes less readable (IMHO)

The $derived.by + untrack() pattern here is basically memoization: "if asset/sharedLink haven't changed, return the cached loader; otherwise create a new one." The other "state"" is really just the previous generation of the same loader. The mutations inside untrack() are specifically to maintain that memoization without creating circular reactivity.

If you want it to run before the DOM renders use $effect.pre?

That may work at runtime, but typescript then need to use !. instead of ?. in about 12 places, though realistically, it can be condensed down to probably 4. I'll try it.

Wouldn't a pattern like this work?

const createAdaptiveImageLoader = () => new AdaptiveImageLoader(asset, sharedLink, { currentZoomFn: () => assetViewerManager.zoom, onImageReady, onError, onUrlChange, }); const loaderKey = $derived(`${asset.id}-${asset.thumbhash}-${sharedLink?.id}`); let adaptiveImageLoader = $state(createAdaptiveImageLoader()); $effect.pre(() => { void loaderKey; untrack(() => { assetViewerManager.resetZoomState(); adaptiveImageLoader = createAdaptiveImageLoader(); }); return () => { adaptiveImageLoader.destroy(); }; });

web/src/lib/components/AdaptiveImage.svelte

web/src/lib/components/Image.svelte

…higher quality images for responsiveness

danieldietzler

Ended up being busy with other stuff and have to run now, so only some superficial comments

danieldietzler · 2026-02-17T15:50:59Z

web/src/lib/actions/image-loader.svelte.ts

+  onStart?: () => void,
+) => {
+  if (!src) {
+    return undefined;


Suggested change

return undefined;

return;

danieldietzler · 2026-02-17T15:52:23Z

web/src/lib/actions/image-loader.svelte.ts

+  if (properties.alt !== undefined) {
+    img.alt = properties.alt;
+  }
+  if (properties.draggable !== undefined) {
+    img.draggable = properties.draggable;
+  }
+  if (properties.loading !== undefined) {
+    img.loading = properties.loading;
+  }


Do you even need these guards? If, for instance, properties.alt is undefined, img.alt will be undefined too since you don't set it anywhere. So, might as well always set img.alt = properties.alt

danieldietzler · 2026-02-17T15:57:39Z

web/src/lib/components/asset-viewer/face-editor/face-editor.svelte

+    const listHeight = Math.min(MAX_LIST_HEIGHT, containerHeight - gap * 2 - chromeHeight);
+    const selectorHeight = listHeight + chromeHeight;
+
+    const clampTop = (top: number) => Math.max(gap, Math.min(top, containerHeight - selectorHeight - gap));


Very minor nit; lodash already provides a clamp helper function https://lodash.com/docs/4.17.23#clamp. That might clean up things a bit here

danieldietzler · 2026-02-17T16:00:11Z

web/src/lib/components/asset-viewer/face-editor/face-editor.svelte

+      const overlapX = Math.max(
+        0,
+        Math.min(position.left + selectorWidth, faceBox.left + faceBox.width) - Math.max(position.left, faceBox.left),
+      );
+      const overlapY = Math.max(
+        0,
+        Math.min(position.top + selectorHeight, faceBox.top + faceBox.height) - Math.max(position.top, faceBox.top),
+      );


This is kind of hard to follow without taking notes 😅 Could you extract some of those intermediate calculations out into their own variables with descriptive names?

danieldietzler · 2026-02-17T16:09:11Z

web/src/lib/actions/image-loader.svelte.ts

+  if (params.alt !== undefined) {
+    img.alt = params.alt;
+  }
+  if (params.draggable !== undefined) {
+    img.draggable = params.draggable;
+  }
+  if (params.imgClass) {
+    img.className = classValueToString(params.imgClass);
+  }
+  if (params.role) {
+    img.role = params.role;
+  }
+  if (params.style !== undefined) {
+    img.setAttribute('style', params.style);
+  }
+  if (params.title !== undefined && params.title !== null) {
+    img.title = params.title;
+  }
+  if (params.loading !== undefined) {
+    img.loading = params.loading;
+  }


To be clear, what I meant is Object.assign(img, properties)

jrasm91 · 2026-02-17T22:16:21Z

This PR has a lot of issues, but the biggest issue is that it is way too big. Please submit pull requests that are of a reasonable size and scope.

midzelis requested a review from danieldietzler as a code owner January 13, 2026 03:45

immich-push-o-matic bot added the 🖥️web label Jan 13, 2026

midzelis added changelog:feature preview and removed 🖥️web labels Jan 13, 2026

midzelis force-pushed the refactor/adaptive_image branch from 6f3f0af to ec48504 Compare January 13, 2026 03:55

immich-push-o-matic bot added the 🖥️web label Jan 13, 2026

midzelis force-pushed the refactor/adaptive_image branch 4 times, most recently from 994bdef to 8a0f839 Compare January 15, 2026 05:06

Base automatically changed from push-qtxrpwpzzmvv to main January 15, 2026 11:55

midzelis force-pushed the refactor/adaptive_image branch from 5d4c3ef to 584dc1e Compare January 15, 2026 15:16

midzelis changed the title ~~refactor: rework photo-viewer/asset-viewer - introduce adaptive-image.svelte, increase performance esp. on low BW conn~~ refactor: rework photo-viewer/asset-viewer - introduce adaptive-image.svelte Jan 15, 2026

midzelis force-pushed the refactor/adaptive_image branch from 2204308 to 0b05772 Compare January 15, 2026 21:49

midzelis added preview and removed preview labels Jan 15, 2026

midzelis force-pushed the refactor/adaptive_image branch 8 times, most recently from 895202e to f6862aa Compare January 20, 2026 15:57

midzelis changed the title ~~refactor: rework photo-viewer/asset-viewer - introduce adaptive-image.svelte~~ feat: rework photo-viewer/asset-viewer - introduce adaptive-image.svelte Jan 20, 2026

midzelis force-pushed the refactor/adaptive_image branch from 6c672b8 to 009def8 Compare January 24, 2026 15:42

midzelis force-pushed the push-lmxsupnmxspl branch from cd15bed to 66bac74 Compare January 24, 2026 15:54

midzelis force-pushed the refactor/adaptive_image branch 2 times, most recently from 0e6eaf2 to 7139757 Compare January 26, 2026 00:24

midzelis force-pushed the push-lmxsupnmxspl branch from 66bac74 to 8dbcea4 Compare January 27, 2026 00:26

midzelis force-pushed the refactor/adaptive_image branch from 7139757 to 70953a5 Compare January 27, 2026 00:26

midzelis force-pushed the push-lmxsupnmxspl branch from 8dbcea4 to c13b1e6 Compare January 28, 2026 15:18

midzelis force-pushed the refactor/adaptive_image branch from 70953a5 to 49791dd Compare January 28, 2026 15:18

midzelis mentioned this pull request Feb 3, 2026

fix: reset zoom when navigating between assets #25863

Merged

midzelis force-pushed the push-lmxsupnmxspl branch from c13b1e6 to a99a085 Compare February 4, 2026 02:31

midzelis force-pushed the refactor/adaptive_image branch 2 times, most recently from f58dcb2 to a705be8 Compare February 4, 2026 04:22

danieldietzler reviewed Feb 5, 2026

View reviewed changes

Base automatically changed from push-lmxsupnmxspl to main February 12, 2026 16:25

midzelis force-pushed the refactor/adaptive_image branch 4 times, most recently from 67a5d22 to d4e7b1b Compare February 15, 2026 20:48

midzelis requested a review from danieldietzler February 15, 2026 21:13

michelheusschen reviewed Feb 16, 2026

View reviewed changes

midzelis force-pushed the refactor/adaptive_image branch 6 times, most recently from 2bdcf0d to 15d3613 Compare February 17, 2026 16:38

feat: rework photo-viewer/asset-viewer - progressively load lower to …

0b59e79

…higher quality images for responsiveness

danieldietzler reviewed Feb 17, 2026

View reviewed changes

midzelis mentioned this pull request Feb 18, 2026

feat: adaptive progressive image loading for photo viewer #26309

Closed

Uh oh!

Conversation

midzelis commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alextran1502 commented Jan 13, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

danieldietzler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jrasm91 commented Feb 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

midzelis commented Jan 13, 2026 •

edited

Loading

github-actions bot commented Jan 13, 2026 •

edited

Loading