diff --git a/quickshell/Modules/Plugins/DesktopPluginComponent.qml b/quickshell/Modules/Plugins/DesktopPluginComponent.qml
index 1fd7ab8fc..4651008d5 100644
--- a/quickshell/Modules/Plugins/DesktopPluginComponent.qml
+++ b/quickshell/Modules/Plugins/DesktopPluginComponent.qml
@@ -14,6 +14,9 @@ Item {
     property real minWidth: 100
     property real minHeight: 100
 
+    property var requestResize: null
+    property var clearResize: null
+
     readonly property bool isInstance: instanceId !== "" && instanceData !== null
     readonly property var instanceConfig: instanceData?.config ?? {}
 
diff --git a/quickshell/Modules/Plugins/DesktopPluginWrapper.qml b/quickshell/Modules/Plugins/DesktopPluginWrapper.qml
index 708cae56b..4213b1343 100644
--- a/quickshell/Modules/Plugins/DesktopPluginWrapper.qml
+++ b/quickshell/Modules/Plugins/DesktopPluginWrapper.qml
@@ -231,6 +231,20 @@ Item {
         dragOverrideH = -1;
     }
 
+    function requestResize(width, height) {
+        if (width < minWidth || height < minHeight)
+            return;
+        if (width > screenWidth || height > screenHeight)
+            return;
+        dragOverrideW = width;
+        dragOverrideH = height;
+    }
+
+    function clearResize() {
+        dragOverrideW = -1;
+        dragOverrideH = -1;
+    }
+
     property real minWidth: contentLoader.item?.minWidth ?? 100
     property real minHeight: contentLoader.item?.minHeight ?? 100
     property bool forceSquare: contentLoader.item?.forceSquare ?? false
@@ -442,6 +456,10 @@ Item {
                     item.widgetHeight = Qt.binding(() => contentLoader.height);
                 if (item.screen !== undefined)
                     item.screen = Qt.binding(() => root.screen);
+                if (item.requestResize !== undefined)
+                    item.requestResize = root.requestResize;
+                if (item.clearResize !== undefined)
+                    item.clearResize = root.clearResize;
             }
         }
 
diff --git a/quickshell/PLUGINS/README.md b/quickshell/PLUGINS/README.md
index fd5c793e5..c22888241 100644
--- a/quickshell/PLUGINS/README.md
+++ b/quickshell/PLUGINS/README.md
@@ -1651,6 +1651,43 @@ Define these properties on your widget to customize behavior:
 - `minWidth`: Minimum allowed width (default: 100)
 - `minHeight`: Minimum allowed height (default: 100)
 
+### Runtime Resize API
+
+Desktop widgets can resize their live surface at runtime without saving the new size to disk.
+
+The wrapper exposes two functions on the widget instance:
+
+- `requestResize(width, height)`: Applies a temporary surface size override
+- `clearResize()`: Clears the temporary override and restores the normal persisted size
+
+These are available as properties on `DesktopPluginComponent` and are passed through by `DesktopPluginWrapper` automatically.
+
+```qml
+import QtQuick
+import qs.Common
+
+Item {
+    id: root
+
+    function expandPreview() {
+        if (requestResize) {
+            requestResize(420, 260)
+        }
+    }
+
+    function resetPreview() {
+        if (clearResize) {
+            clearResize()
+        }
+    }
+}
+```
+
+Notes:
+- This is a transient runtime resize only; it does not persist to `settings.json`
+- The requested size must stay within the screen bounds and above `minWidth` / `minHeight`
+- Use `clearResize()` when you want to return to the saved widget dimensions
+
 ### Loading and Saving Data
 
 Use the injected `pluginService` to persist widget-specific data: