home-assistant.io/source/_dashboards/picture-elements.markdown

type, title, sidebar_label, description

type	title	sidebar_label	description
card	Picture elements card	Picture elements	The picture elements card is one of the most versatile types of cards. The cards allow you to position icons or text and even services! On an image based on coordinates.

The picture elements card is one of the most versatile types of cards.

A functional floorplan powered by picture elements.

The cards allow you to position icons or text and even services on an image based on coordinates. Imagine floor plan, imagine picture-glance with no restrictions!

{% include dashboard/edit_dashboard.md %}

YAML configuration

This card can only be configured in YAML.

{% configuration %} type: required: true description: "picture-elements" type: string image: required: true description: The URL of an image.
To use a locally hosted image, see Hosting. type: string camera_image: required: false description: A camera entity. type: string camera_view: required: false description: '"live" will show the live view if stream is enabled.' default: auto type: string elements: required: true description: List of elements. type: list title: required: false description: Card title. type: string state_filter: required: false description: 'State-based CSS filters' type: map theme: required: false description: Override the used theme for this card with any loaded theme. For more information about themes, see the frontend documentation. type: string dark_mode_image: required: false description: "This image is used when the dark mode is activated and no state image is set." type: string dark_mode_filter: required: false description: "This CSS filter is used when the dark mode is activated." type: string {% endconfiguration %}

Elements

Elements are the active components (icons, badges, buttons, text, etc.) that overlay the image.

There are several different element types that can be added to a Picture Elements card:

• State badge
• State Icon
• State Label
• Service Call Button
• Icon
• Image
• Conditional
• Custom

State badge

This element creates a badge representing the state of an entity.

{% configuration %} type: required: true description: "state-badge" type: string entity: required: true description: Entity ID. type: string style: required: true description: 'Position and style the element using CSS.' type: map default: "position: absolute, transform: translate(-50%, -50%)" title: required: false description: State badge tooltip. Set to null to hide. type: string tap_action: required: false description: Action taken on card tap. See action documentation. type: map hold_action: required: false description: Action taken on card tap and hold. See action documentation. type: map double_tap_action: required: false description: Action taken on card double tap. See action documentation. type: map {% endconfiguration %}

State icon

This element represents an entity state using an icon.

{% configuration %} type: required: true description: "state-icon" type: string entity: required: true description: The entity ID to use. type: string icon: required: false description: Overwrites icon. type: string title: required: false description: Icon tooltip. Set to null to hide. type: string state_color: required: false description: Set to true to have icons colored when entity is active. type: boolean default: true tap_action: required: false description: Action taken on card tap. See action documentation. type: map hold_action: required: false description: Action taken on card tap and hold. See action documentation. type: map double_tap_action: required: false description: Action taken on card double tap. See action documentation. type: map style: required: true description: 'Position and style the element using CSS.' type: string default: "position: absolute, transform: translate(-50%, -50%)" {% endconfiguration %}

State label

This element represents an entity's state via text.

{% configuration %} type: required: true description: "state-label" type: string entity: required: true description: Entity ID. type: string attribute: required: false description: If present, the corresponding attribute will be shown, instead of the entity's state. type: string prefix: required: false description: Text before entity state. type: string suffix: required: false description: Text after entity state. type: string title: required: false description: Label tooltip. Set to null to hide. type: string tap_action: required: false description: Action taken on card tap. See action documentation. type: map hold_action: required: false description: Action taken on card tap and hold. See action documentation. type: map double_tap_action: required: false description: Action taken on card double tap. See action documentation. type: map style: required: true description: 'Position and style the element using CSS.' type: string default: "position: absolute, transform: translate(-50%, -50%)" {% endconfiguration %}

Service call button

This entity creates a button (with arbitrary text) that can be used to call a service.

{% configuration %} type: required: true description: "service-button" type: string title: required: true description: Button label. type: string service: required: true description: "light.turn_on" type: string service_data: required: false description: The service data to use. type: map style: required: true description: 'Position and style the element using CSS.' type: string default: "position: absolute, transform: translate(-50%, -50%)" {% endconfiguration %}

Icon element

This element creates a static icon that is not linked to the state of an entity.

{% configuration %} type: required: true description: "icon" type: string icon: required: true description: "Icon to display (e.g., mdi:home)." type: string title: required: false description: Icon tooltip. Set to null to hide. type: string entity: required: false description: Entity to use for more-info/toggle. type: string tap_action: required: false description: Action taken on card tap. See action documentation. type: map hold_action: required: false description: Action taken on card tap and hold. See action documentation. type: map double_tap_action: required: false description: Action taken on card double tap. See action documentation. type: map style: required: true description: 'Position and style the element using CSS.' type: string default: "position: absolute, transform: translate(-50%, -50%)" {% endconfiguration %}

Image element

This creates an image element that overlays the background image.

{% configuration %} type: required: true description: "image" type: string entity: required: false description: "Entity to use for state_image and state_filter and also target for actions." type: string title: required: false description: Image tooltip. Set to null to hide. type: string tap_action: required: false description: Action taken on card tap. See action documentation. type: map hold_action: required: false description: Action taken on card tap and hold. See action documentation. type: map double_tap_action: required: false description: Action taken on card double tap. See action documentation. type: map image: required: false description: The image to display. type: string camera_image: required: false description: A camera entity. type: string camera_view: required: false description: '"live" will show the live view if stream is enabled.' default: auto type: string state_image: required: false description: 'State-based images' type: map filter: required: false description: "Default: grayscale(100%) when entity state is off. Set to none to remove this." type: string state_filter: required: false description: 'State-based CSS filters' type: map aspect_ratio: required: false description: 'Forces the height of the image to be a ratio of the width. Valid formats: Height percentage value (23%) or ratio expressed with colon or "x" separator (16:9 or 16x9). For a ratio, the second element can be omitted and will default to "1" (1.78 equals 1.78:1).' type: string default: "50%" style: required: true description: 'Position and style the element using CSS.' type: string default: "position: absolute, transform: translate(-50%, -50%)" {% endconfiguration %}

Conditional element

Much like the Conditional card, this element will let you show its sub-elements based on entity states.

{% configuration %} type: required: true description: "conditional" type: string conditions: required: true description: List of entity IDs and matching states. type: list keys: entity: required: true description: Entity ID. type: string state: required: false description: Entity state is equal to this value.* type: string state_not: required: false description: Entity state is unequal to this value.* type: string elements: required: true description: One or more elements of any of the listed types to show when conditions are met. See below for an example. type: list {% endconfiguration %}

Custom elements

The process for creating and referencing custom elements is the same as for custom cards. Please see the developer documentation for more information.

{% configuration %} type: required: true description: 'Card name with custom: prefix (e.g., custom:my-custom-card).' type: string style: required: true description: 'Position and style the element using CSS.' type: string default: "position: absolute, transform: translate(-50%, -50%)" {% endconfiguration %}

Options for exemptions

{% configuration badges %} user: required: true description: User ID that can see the view tab. type: string {% endconfiguration %}

Notes on Element Attributes

How to use the style object

Position and style your elements using CSS. More/other keys are also possible. Note, the default style for most elements includes translate(-50%, -50%), which means that the coordinates you provide will set the position of the center of the element. Use transform: none to disable this behavior.

style:
  # Positioning of the element
  left: 50%
  top: 50%

How to use state_image

Specify a different image to display based on the state of the entity.

state_image:
  "on": /local/living_room_on.jpg
  "off": /local/living_room_off.jpg

How to use state_filter

Specify different CSS filters

state_filter:
  "on": brightness(110%) saturate(1.2)
  "off": brightness(50%) hue-rotate(45deg)

How to use click-and-hold

If the option hold_action is specified, that action will be performed when the entity is clicked and held for half a second or more.

tap_action:
  action: toggle
hold_action:
  action: call-service
  service: light.turn_on
  data:
    entity_id: light.bed_light
    brightness_pct: 100

Examples

Example of icons, labels and buttons

type: picture-elements
image: /local/floorplan.png
elements:
  - type: state-icon
    tap_action:
      action: toggle
    entity: light.ceiling_lights
    style:
      top: 47%
      left: 42%
  - type: state-icon
    tap_action:
      action: toggle
    entity: light.kitchen_lights
    style:
      top: 30%
      left: 15%
  - type: state-label
    entity: sensor.outside_temperature
    style:
      top: 82%
      left: 79%
  - type: state-label
    entity: climate.kitchen
    attribute: current_temperature
    suffix: "°C"
    style:
      top: 33%
      left: 15%
  - type: service-button
    title: Turn lights off
    style:
      top: 95%
      left: 60%
    service: homeassistant.turn_off
    service_data:
      entity_id: group.all_lights
  - type: icon
    icon: mdi:home
    tap_action:
      action: navigate
      navigation_path: /lovelace/0
    style:
      top: 10%
      left: 10%

Images example

type: picture-elements
image: /local/floorplan.png
elements:
  # state_image & state_filter - toggle on click
  - type: image
    entity: light.living_room
    tap_action:
      action: toggle
    image: /local/living_room.png
    state_image:
      "off": /local/living_room_off.png
    filter: saturate(.8)
    state_filter:
      "on": brightness(120%) saturate(1.2)
    style:
      top: 25%
      left: 75%
      width: 15%
  # Camera, red border, rounded-rectangle - show more-info on click
  - type: image
    entity: camera.driveway_camera
    camera_image: camera.driveway_camera
    style:
      top: 5%
      left: 10%
      width: 10%
      border: 2px solid red
      border-radius: 10%
  # Single image, state_filter - call-service on click
  - type: image
    entity: media_player.living_room
    tap_action:
      action: call-service
      service: media_player.media_play_pause
      data:
        entity_id: media_player.living_room
    image: /local/television.jpg
    filter: brightness(5%)
    state_filter:
      playing: brightness(100%)
    style:
      top: 40%
      left: 75%
      width: 5%

Conditional example

type: picture-elements
image: /local/House.png
elements:
  # conditionally show TV off button shortcut when dad's away and daughter is home
  - type: conditional
    conditions:
      - entity: sensor.presence_daughter
        state: "home"
      - entity: sensor.presence_dad
        state: "not_home"
    elements:
      - type: state-icon
        entity: switch.tv
        tap_action:
          action: toggle
        style:
          top: 47%
          left: 42%