feat: replace asset option for image assets in asset details by shreyanshkotak · Pull Request #5676 · webstudio-is/webstudio

shreyanshkotak · 2026-04-03T17:26:50Z

Description

Adds the ability to replace an existing image asset with a new file directly from the asset details panel, without having to delete and re-upload manually. Related to place an image so that it gets replaced automatically everywhere its being used #3268

When clicking the new replace button on an image asset:

A file picker opens filtered to image MIME types
The new file is uploaded via the existing upload pipeline
All references to the old asset (props, styles, page meta: favicon, social image, marketplace thumbnail) are atomically re-pointed to the new asset
The old asset's filename and description are copied to the new asset
The old asset is deleted

A new ReverseIcon from the Figma library was added to the icons package to represent the replace action.

Steps for reproduction

Open the asset manager and select any image asset
In the asset details panel, click the new replace icon button next to the download button
Select a new image file from the file picker
Expect the asset to be replaced in place - all usages (image props, background styles, favicon, social image) should now reference the new file with the original asset's filename preserved

Code Review

hi @kof, I need you to do
- conceptual review (architecture, feature-correctness)
- detailed review (read every line)
- test it on preview

Before requesting a review

made a self-review
added inline comments where things may be not obvious (the "why", not "what")

Before merging

tested locally and on preview environment (preview dev login: 0000)
updated test cases document
added tests
if any new env variables are added, added them to .env file

Add a 'Replace Asset' button (RefreshIcon) next to the download button in the asset details popover. This is only shown for image-type assets. When triggered, the user selects a new image file which is uploaded via the existing pipeline. All references to the original asset (props, styles, page meta) are atomically re-pointed to the new asset in a single transaction. The original asset's filename and description (alt text) are preserved on the replacement. The old asset is then deleted. - New module: replace-asset.ts with replaceAsset() function - Updated asset exports in index.ts - Modified asset-info.tsx to render replace button (disabled in view mode)

Add a new ReverseIcon and use it for the asset replace action in the builder UI.

Use $assets.subscribe() instead of a setTimeout loop so waitForAsset resolves as soon as the upload completes, regardless of network speed. Removes the arbitrary 60s timeout and 500ms polling interval.

Props with type "asset" hold an asset ID reference and can not represent width or height, which are always type "number" per the schema. The name checks were dead code.

shreyanshkotak · 2026-04-10T02:34:42Z

@kof resolved all the items mentioned in the review

github-actions · 2026-04-10T11:03:33Z

🚀 Deployed!

📍 Preview: https://pr-5676.development.webstudio.is

Note: Adding new commits will remove the safe-to-deploy label and require re-approval.

kof · 2026-04-10T11:13:10Z

Found a bug after testing:

create an image instance, choose an image 1
hit replace image to replace it for image 2
Hit undo shortcut
See we now have both images in the assets panel (not sure if this is expected but not a big deal imho)
Delete image 2
Try to replace image 1 again with the same image 2
See error toast: "Cannot access 't' before initialization"

notification-popover-CjwxmI7J.js:14 Uncaught (in promise) ReferenceError: Cannot access 't' before initialization
    at notification-popover-CjwxmI7J.js:14:11937
    at Object.subscribe (index-3whys8t3.js:1:488)
    at notification-popover-CjwxmI7J.js:14:11893
    at new Promise (<anonymous>)
    at hT (notification-popover-CjwxmI7J.js:14:11866)
    at cT (notification-popover-CjwxmI7J.js:14:11095)

If I reload and do step 6 again - it will work.

$assets.subscribe() fires its callback synchronously, causing a "Cannot access 't' before initialization" ReferenceError when the asset already exists in the store (e.g. after undo → delete → re-replace). Check current value with .get() first for an early return, and use .listen() instead of .subscribe() to avoid the synchronous callback.

shreyanshkotak · 2026-04-10T11:52:40Z

@kof good catch! This was a TDZ bug in waitForAsset — nanostores .subscribe() fires synchronously, so when the asset already exists in the store (which happens in this undo → delete → re-replace flow), unsubscribe is referenced before assignment.

fixed in the latest commit.

kof · 2026-04-10T17:11:07Z

merged 🎉

shreyanshkotak and others added 7 commits April 2, 2026 23:01

chrore: documentation cleanup

f0bb724

feat: new icon for asset replacement

67fd9bb

Add a new ReverseIcon and use it for the asset replace action in the builder UI.

Merge branch 'webstudio-is:main' into replace-assets

a2541ff

test: add unit tests for replace asset

04ae7f8

docs: add test cases for asset replacement

b6abb6e

chore: documentation cleanup

50d16d2

shreyanshkotak temporarily deployed to development April 3, 2026 17:26 — with GitHub Actions Inactive

shreyanshkotak temporarily deployed to empty April 3, 2026 17:26 — with GitHub Actions Inactive

shreyanshkotak temporarily deployed to development April 3, 2026 17:26 — with GitHub Actions Inactive

shreyanshkotak mentioned this pull request Apr 7, 2026

Replace an image so that it gets replaced automatically everywhere its being used #3268

Open