From 228874a52b268070199dc37f4622cca1361e729b Mon Sep 17 00:00:00 2001
From: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
Date: Wed, 25 Feb 2026 10:45:50 -0500
Subject: [PATCH] [config] Improve dimensions validation and fix online_image
 resize aspect ratio (#14274)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 esphome/components/runtime_image/runtime_image.cpp | 9 +++++++++
 esphome/config_validation.py                       | 5 ++++-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/esphome/components/runtime_image/runtime_image.cpp b/esphome/components/runtime_image/runtime_image.cpp
index 603ea76f01a..5a4a2ea7d69 100644
--- a/esphome/components/runtime_image/runtime_image.cpp
+++ b/esphome/components/runtime_image/runtime_image.cpp
@@ -2,6 +2,7 @@
 #include "image_decoder.h"
 #include "esphome/core/log.h"
 #include "esphome/core/helpers.h"
+#include <algorithm>
 #include <cstring>
 
 #ifdef USE_RUNTIME_IMAGE_BMP
@@ -43,6 +44,14 @@ int RuntimeImage::resize(int width, int height) {
   int target_width = this->fixed_width_ ? this->fixed_width_ : width;
   int target_height = this->fixed_height_ ? this->fixed_height_ : height;
 
+  // When both fixed dimensions are set, scale uniformly to preserve aspect ratio
+  if (this->fixed_width_ && this->fixed_height_ && width > 0 && height > 0) {
+    float scale =
+        std::min(static_cast<float>(this->fixed_width_) / width, static_cast<float>(this->fixed_height_) / height);
+    target_width = static_cast<int>(width * scale);
+    target_height = static_cast<int>(height * scale);
+  }
+
   size_t result = this->resize_buffer_(target_width, target_height);
   if (result > 0 && this->progressive_display_) {
     // Update display dimensions for progressive display
diff --git a/esphome/config_validation.py b/esphome/config_validation.py
index ef1c66a20e1..3b0e4da298a 100644
--- a/esphome/config_validation.py
+++ b/esphome/config_validation.py
@@ -1640,7 +1640,10 @@ def dimensions(value):
         if width <= 0 or height <= 0:
             raise Invalid("Width and height must at least be 1")
         return [width, height]
-    value = string(value)
+    if not isinstance(value, str):
+        raise Invalid(
+            "Dimensions must be a string (WIDTHxHEIGHT). Got a number instead, try quoting the value."
+        )
     match = re.match(r"\s*([0-9]+)\s*[xX]\s*([0-9]+)\s*", value)
     if not match:
         raise Invalid(