Add use_entity_picture option to picture-entity card

[DTekNOdev]

Proposed change

Picture-entity cards currently only use the entity_picture attribute automatically for person and image domain entities. This PR adds an optional use_entity_picture toggle to extend this capability to all entity types.

Motivation

Previously, users had to manually configure static image URLs for these entities, even when the entity already provided a picture. This enhancement allows any entity to use its entity_picture attribute, just like person entities do.

Many entities beyond the person/image domains set the entity_picture attribute:

• Update entities display component/integration logos
• Custom integrations may set dynamic entity pictures
• Media players show album art when playing
• Other core entities that have associated imagery

Changes

Changes

• Add use_entity_picture boolean option to PictureEntityCardConfig
• Implement logic to check entity_picture attribute when enabled
• Update validation to accept use_entity_picture as valid image source
• Add editor toggle with helper text
• Add translation strings for the new option

The configured static image remains as a fallback when entity_picture is not present or when the toggle is disabled.

Example

type: picture-entity
entity: update.home_assistant_core_update
use_entity_picture: true
show_state: true
show_name: true

Screenshots

Custom integration providing entity picture (HACS norway_alerts integration)

show_state: true
show_name: true
type: picture-entity
entity: sensor.norway_alerts_metalerts_vestland
use_entity_picture: true
name:
  type: device

Custom integration with manufacturers api provided url as entity_picture (HACS mspa integration)

show_state: true
show_name: true
type: picture-entity
entity: sensor.mspa_oslouvc_bobbyspa_water_temperature
use_entity_picture: true
name:
type: entity

Media player

show_state: true
show_name: true
type: picture-entity
entity: media_player.roam_2
use_entity_picture: true

Switching media sources with music assistant and updating picture entity image through entity_picture

Music assistant on the left, entity picture on the right

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New feature (thank you!)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes #
• This PR is related to issue or discussion:
• Link to documentation pull request: Add use_entity_picture option to picture-entity card #51553
• Link to developer documentation pull request:
• Link to backend pull request:

Checklist

• I understand the code I am submitting and can explain how it works.
• The code change is tested and works locally.
• There is no commented out code in this PR.
• I have followed the development checklist
• I have followed the perfect PR recommendations
• Any generated code has been carefully reviewed for correctness and compliance with project standards.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for www.home-assistant.io

To help with the load of incoming pull requests:

• I have reviewed two other open pull requests in this repository.

[karwosts]

Person entities already show their entity picture in this card, so that isn't really a good example usecase.

media_player is the other example I could maybe think of, but their entity_picture is conditional, it isn't always present when it is not playing.

[DTekNOdev]

Person entities already show their entity picture in this card, so that isn't really a good example usecase.

media_player is the other example I could maybe think of, but their entity_picture is conditional, it isn't always present when it is not playing.

Thanks, working on it, agreed about person entity, ill remove the example before publishing the pr. I have lots of custom integrations using entity picture, which is why I wanted this implemented, but I was trying to avoid using those as primary examples.

[karwosts]

I'm wondering if maybe this would be a problem for image entities. If you enable use_entity_picture, then we bypass the computeImageUrl function, which uses the state I guess to flush cached image?

I'm not sure if enabling this would have negative effect for camera entities as well. I wonder if it's a little confusing in those cases.

[home-assistant]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

[DTekNOdev]

I'm wondering if maybe this would be a problem for image entities. If you enable use_entity_picture, then we bypass the computeImageUrl function, which uses the state I guess to flush cached image?

I'm not sure if enabling this would have negative effect for camera entities as well. I wonder if it's a little confusing in those cases.

I'm not sure if this fully answers your question, but here's how show_entity_picture behaves in all combinations:

show_entity_picture	image configured	entity_picture attribute	Image displayed
✅ Enabled	✅ Yes	✅ Present	Entity picture (attribute)
✅ Enabled	✅ Yes	❌ Absent	Configured image (fallback)
✅ Enabled	❌ No	✅ Present	Entity picture (attribute)
✅ Enabled	❌ No	❌ Absent	Stub image*
❌ Disabled	✅ Yes	✅ Present	Configured image (current behavior)
❌ Disabled	✅ Yes	❌ Absent	Configured image (current behavior)
❌ Disabled	❌ No	✅ Present	Domain fallback** (current behavior)
❌ Disabled	❌ No	❌ Absent	Domain fallback** (current behavior)

* Stub image for entities outside camera/image/person domains
** Domain-specific fallback for person/image domains, otherwise stub image

Key behavior:

• When show_entity_picture is enabled, it prioritizes entity_picture_local → entity_picture → configured image → fallback
• When disabled, it uses the configured image and ignores the entity's entity_picture attribute
• The configured image acts as a fallback when show_entity_picture is enabled but the attribute is absent

[karwosts]

I'm not sure if this fully answers your question, but here's how show_entity_picture behaves in all combinations:

No I don't think you really hit on the issue, let me try to rephrase.

An image entity, with show_entity_picture off, uses the entity picture URL with a '&state=...' suffix appended to the url.

An image entity, with show_entity_picture on, uses the same entity picture URL without the suffix. I think that means when the image entity updates, it won't automatically update to the new picture if show_entity_picture is on, because it will keep hitting the stale cached version.

I'm just a little worried the behavior difference will confuse people because they won't really understand if they should enable this option or not for entities which already show the entity picture.

[DTekNOdev]

I'm not sure if this fully answers your question, but here's how show_entity_picture behaves in all combinations:

No I don't think you really hit on the issue, let me try to rephrase.

An image entity, with show_entity_picture off, uses the entity picture URL with a '&state=...' suffix appended to the url.

An image entity, with show_entity_picture on, uses the same entity picture URL without the suffix. I think that means when the image entity updates, it won't automatically update to the new picture if show_entity_picture is on, because it will keep hitting the stale cached version.

I'm just a little worried the behavior difference will confuse people because they won't really understand if they should enable this option or not for entities which already show the entity picture.

After investigating further, hui-image already calls computeImageUrl() directly for image domain entities regardless of the URL passed in, so cache-busting is handled automatically. The show_entity_picture option therefore works correctly for image entities without any special casing needed.

Tested now with a template image like this and updating is working also whether or not show_entity_picture is enabled. The picture changes every 30 seconds (default update), and the lighting effect changes when the light is turned on/off.

template:
  - image:
      - name: "test_image"
        url: "https://picsum.photos/800/600?r={{ now().minute }}"

[DTekNOdev]

Thanks for the review @MindFreeze — I've addressed both suggestions in the latest push:

• Renamed to show_entity_picture to match the existing convention in tile/badge cards
• Used entity_picture_local || entity_picture pattern as suggested
• Removed the else so the configured static image is properly used as fallback when entity_picture is absent

One question while we're here: would it make sense to simplify this further by removing the toggle entirely and just automatically using entity_picture when no image is configured? That way users who just want their entity's picture don't need to know about the toggle at all. The explicit option would only be needed if someone wants entity_picture to override a configured image, which seems like an edge case.

Happy to go in either direction — just wanted to raise it before this gets merged.

[MindFreeze]

I wouldn't remove the toggle because tile and badge cards already have the same toggle. image is also auto populated by the stub so an empty image is not that discoverable