Markdown Card Image Resizing Bug In Home Assistant
Hey there, Home Assistant enthusiasts! If you've recently updated your Home Assistant to version 2025.12, you might have stumbled upon a rather frustrating issue: markdown card images are no longer resizing as expected. This is a big deal, especially if you rely on custom cards to display information with specific image dimensions. Many users are reporting the same problem, and it seems to have appeared overnight after the update from 2025.11 to 2025.12. Let's dive into what's happening and explore potential workarounds.
The Unexpected Change in Image Behavior
The core of the problem lies in how markdown cards handle images after the 2025.12 update. Previously, in version 2025.11, users could specify width and height attributes directly within the <img> tags in their markdown content, and these would be respected, allowing for precise control over image dimensions. This was particularly useful for creating visually appealing and organized dashboards. However, with the latest release, it appears these attributes are being ignored, and images are defaulting to height: auto, width: auto, and max-width: 100%. This change, while potentially intended to make markdown more responsive, has broken the existing functionality for many.
This issue was identified by multiple users, all experiencing the same behavior after updating. The provided code snippet showcases a typical markdown card setup that was working perfectly in 2025.11 but is now failing to resize images in 2025.12. The image in question, linked via https://brands.home-assistant.io/watchman/dark_logo.png, along with other images within the markdown content, no longer adheres to the specified dimensions. Instead, they expand to fill available space or shrink to fit, overriding any explicit size constraints set in the card's configuration. This can lead to broken layouts, unreadable content, and a generally less polished user experience. The good news is that the community is actively investigating this, and the root cause has been identified as changes made to the frontend's markdown processing. The specific commit mentioned, Add markdown support for assist messages (#27957), suggests that enhancements related to assist messages might have inadvertently affected the general markdown image handling.
Why This is a Problem for Your Dashboard
For those who meticulously craft their Home Assistant dashboards, this image resizing issue can be a significant setback. Imagine you have a custom card displaying weather forecasts, security camera feeds, or energy usage reports, and you've used specific image sizes to ensure clarity and aesthetic appeal. Suddenly, these images are either too large, obscuring other content, or too small, rendering them useless. This isn't just an aesthetic problem; it can impact the usability and functionality of your smart home interface. If critical information is presented poorly due to unexpected image scaling, it can lead to confusion and misinterpretation.
Furthermore, the flexibility offered by width and height attributes in markdown images is not just about looks; it's about responsive design and information hierarchy. Developers often use these attributes to ensure that images fit within specific card layouts, maintain aspect ratios, and don't overwhelm the user with excessively large or tiny visuals. For instance, in a custom report card showing multiple status indicators, each with a small, distinct icon, the inability to control the icon size could break the entire card's layout. The card_mod styles applied in the example, such as max-height: 450px and overflow-y: auto, are intended to manage the card's overall dimensions, but they can't compensate when individual image elements within the markdown refuse to cooperate. The fact that this worked flawlessly in 2025.11 highlights a regression in the frontend's markdown parsing, and the community's immediate reporting of this issue underscores its importance.
Troubleshooting Steps You Can Take Right Now
Before we explore potential solutions, let's ensure you've covered the basics. Home Assistant's frontend can sometimes be a bit quirky, and a few standard troubleshooting steps can often resolve unexpected issues. First and foremost, always ensure you have updated to the latest available Home Assistant version. While this specific issue appeared after updating to 2025.12, sometimes minor patches or related fixes are released shortly after. Double-check if a 2025.12.x patch has been deployed.
Secondly, clear your browser's cache. Browsers often store cached versions of website elements, and an outdated cache can lead to unexpected rendering issues. Go into your browser's settings and clear the cache and cookies, then restart your browser and reload your Home Assistant instance. This ensures you're loading the latest frontend code. Try a different browser as well. If the issue persists in Chrome but not in Firefox or Edge, it might indicate a browser-specific rendering bug or an issue with browser extensions interfering with Home Assistant's frontend.
Finally, and this is crucial for ruling out custom component conflicts, try reproducing the issue in Home Assistant's safe mode. You can restart your Home Assistant instance into safe mode from the developer tools or by using the specific command if you're running it via Docker or a supervised installation. Safe mode temporarily disables all custom cards and integrations, allowing you to see if the problem lies with your core setup or with a third-party add-on. If the markdown card images resize correctly in safe mode, you'll know that one of your custom cards or integrations is the culprit, and you can then re-enable them one by one to pinpoint the offender. Following these steps will help isolate the problem and confirm if it's a core Home Assistant bug or something else.
Understanding the Root Cause: Frontend Changes
The developers have shed some light on the cause of this image resizing problem. It stems from recent changes made to the Home Assistant frontend, specifically related to how markdown content is processed. As noted in the issue description and confirmed by the commit linked (home-assistant/frontend@4a90331), the changes were introduced to improve markdown support for assist messages. While this is a valuable enhancement for the conversational AI features, it appears to have had an unintended side effect on the general rendering of images within markdown cards.
Historically, markdown parsers often treated <img> tags with explicit width and height attributes as definitive instructions for rendering. However, modern web development practices, and likely the changes in the Home Assistant frontend, now prioritize responsive design principles. This means that images are often automatically styled with height: auto, width: auto, and max-width: 100%. This approach ensures that images scale gracefully across different screen sizes and devices, preventing them from overflowing their containers or becoming disproportionately large. The intention behind this change was likely to create a more consistent and adaptable user interface, especially as Home Assistant is accessed on a wide variety of devices, from desktops to mobile phones.
However, for users who relied on hardcoding specific pixel dimensions for layout control, this shift represents a breaking change. The frontend is now applying a set of default styles that override the width and height attributes specified in the markdown. This is why the markdown card images, which previously respected these attributes in 2025.11, are now behaving differently in 2025.12. The card_mod styles in the provided example, aiming to control the overall card's appearance, cannot counteract these fundamental changes in how the <img> tags themselves are rendered by the updated markdown processor. It's a classic case of a feature enhancement unintentionally impacting existing functionality.
Workarounds and Potential Solutions
Given that this is a bug introduced in the core frontend, the most definitive solution will be a fix released by the Home Assistant developers. However, while we wait for that, there are a few workarounds you can employ to regain some control over your image sizing. The most direct approach involves leveraging CSS within your markdown content or using card-mod more extensively. Since the frontend is now applying max-width: 100% and width: auto, you can try to override these styles using inline CSS within your <img> tags.
Instead of just using <img src="..." width="100" height="50">, you can try specifying the styles directly: <img src="..." style="width: 100px !important; height: 50px !important; max-width: 100px !important;">. The !important flag is crucial here, as it helps to ensure your custom styles take precedence over the frontend's default styles. You might need to experiment with the values and potentially remove the height attribute if you want to maintain the aspect ratio while controlling the width. For example, <img src="..." style="width: 150px !important; height: auto !important;"> could work if you primarily want to set the width.
Another avenue is to modify the card_mod styles associated with your markdown card. While the issue seems to be with the <img> tag itself, you might be able to target images within the markdown card more specifically. For instance, you could try adding a style to your ha-card.type-markdown like this:
card_mod:
style: |
ha-card.type-markdown img {
width: 100px !important;
height: 50px !important;
max-width: 100px !important;
}
Remember to adjust 100px and 50px to your desired dimensions. This approach attempts to apply consistent styling to all images within that specific markdown card. It's important to note that these are workarounds, and their effectiveness might vary depending on the complexity of your markdown and the exact way the frontend is applying its styles. The best long-term solution is to keep an eye on the Home Assistant GitHub repository for updates and bug fixes related to this issue. The community is actively discussing this, and a fix is likely on its way.
The Path Forward: Community and Updates
This markdown image resizing bug is a prime example of how even small changes in software updates can have a ripple effect, impacting user experience and dashboard functionality. The swift reporting by users and the quick identification of the root cause by developers highlight the strength and collaborative nature of the Home Assistant community. While it's frustrating to encounter such issues, knowing that a fix is likely in the pipeline is reassuring.
For now, implementing the CSS workarounds mentioned above should help you restore the intended appearance of your markdown cards. Remember to test these solutions thoroughly with your specific content to ensure they achieve the desired result. Keep your Home Assistant instance updated, and actively follow the official Home Assistant GitHub repository for any new releases or discussions pertaining to this frontend issue. By staying informed and leveraging community knowledge, you can navigate these challenges and continue to build a powerful and personalized smart home experience.
We are all in this together as part of the vibrant Home Assistant community. If you found this explanation helpful, or if you have discovered another workaround, feel free to share it in the comments below or on the official Home Assistant forums. Your input helps everyone!
