Home Assistant Elements¶

Elements can be connected to the Home Assistant client by giving them an entity key in their config. This signals to the client that it should update this element when the entity’s state changes. Using state_styles and attribute_styles the properties of an element can be updated according to the entity’s state. Buttons and Icons can be used with any element, with the latter showing the entity’s state by default. If an element should reflect the state of an attribute instead, the entity_attribute key can be set. Sliders, Counters and DropDowns can also be used as is, although their entity’s a limited to appropriate domains.

See Examples for how to style elements using state_styles and attribute_styles.

The client also supplies various elements itself, which make it a lot more convenient to implement certain entity types and control them. These elements can be used and configured in the same way as regular elements. The only requirement is that their type is prefixed with an identifier: HA:.

- type: HA:StateButton
  entity: sensor.temperature

All available elements are listed below.

class StateButton¶

Button displaying the state of an entity as text.

Comes with some additional functionality to display the state to your liking.

Available shorthand actions are:

generate: Generates the element’s image data.
update: Function to update an element via actions.

Element Properties

Full

property entity: str: Required. The entity_id of the entity associated with this element. Can be changed, but that will also mean the old entity is not linked anymore.

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the element background.

Optional, defaults to None

property font_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: The color of the font.

Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the elements outline. Set to None to use no outline (i.e. the background color).

Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is held. Set to None to have nothing called. If set to a dict, the values for hold_action_data and hold_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is released from being held down. This function is only available on devices with the HOLD_RELEASE feature. Set to None to have nothing called. If set to a dict, the values for hold_release_action_data and hold_release_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is tapped. Set to None to have nothing called. If set to a dict, the values for tap_action_data and tap_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property attribute_styles: attribute_stylesDict: Element styling as determined by the values of attributes. This is somewhat advanced, and the conditions are very flexible. This may come at the cost of both performance and security, as it may enable executing random code (I am not sure, I am not a programmer. Please notify me if it is really bad).

Optional, defaults to []

property entity_attribute: str | None: The entity’s attribute being shown as the element’s state. Set to None to use the state (default) If the attribute is not present the button will display no text.

Optional, defaults to None

property feedback_duration: duration: Duration of the element’s feedback function The time an element will stay in ‘feedback state’, before returning to its normal state. Can be set to a string, which will be parsed to the right amount of seconds.

Optional, defaults to 0.75

property fit_text: bool: Adjusts the font size automatically to make it fit. If true, font_size will be used as a minimum allowed font_size.

Optional, defaults to False

property font: The path to the element’s font. If set to a shorthand font, the path will automatically be parsed.

Optional, defaults to "default"

property font_size: str | int | float: The size of the font.

Optional, defaults to "H*0.036"

property margins: tuple[int, int, int, int]: The text margins. Always returns a 4 tuple, but can be set to a single number, or two/three/four item iterable. Same as css margins, so the values are returned as (top,right,bottom,left), and set according to css margins (https://www.w3schools.com/css/css_margin.asp).

Optional, defaults to 0

property multiline: bool: Allows the button to try and fit its text over multiple lines. May not work very well with the settings that automatically set the font size.

Optional, defaults to False

property outline_width: str | int | float: The width of the outline of the background rectangle.

Optional, defaults to 1

property prefix_attribute: str | None: Entity attribute to get the prefix from. Overwrites the value of prefix if not None.

Optional, defaults to None

property prefix_separator: str: Character(s) to separate the state text and the prefix. Set to None for no separator.

Optional, defaults to None

property radius: str | int | float: Corner radius of the encapsulating rectangle. Currently only accepts integers.

Optional, defaults to 0

property resize: bool | str | int | float: Tracks the font_size and adjusts it to fit. The resize value updates and will be used as a starting point for the next update. If not False, will use this value as a minimum allowed size for any text displayed. Changes the font_size parameter when needed, such that the text size won’t change with every new text. Sizes are not saved upon resets, so finding a good size takes a few changes. The same goes when the element is resized.

Optional, defaults to False

property state_colors: bool: Allows the element’s color configured state colors. Only if the main color property is not defined in the dict for the state.

Optional, defaults to False

property state_conditionals: bool: The element will first treat the keys in the state_styles dict as possible conditions. The first condition to return true will be used to configure the element’s attributes. If none return True, it will check if the state is present as a key, and only then will use the default element_state if provided.

Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Dict mapping entity states (or entity attribute if set) to element properties. Applies the properties corresponding to the state that matched a key. You can also add a default key to use for undefined states. Some default trigger functions deal with the Unavailable and Unknown states, but these can be overwritten. If a key returns a string instead of a dict, the value is used to update the base attribute (i.e. set a new icon for Icon elements.).

Optional, defaults to {}

property suffix_attribute: str | None: Entity attribute to get the suffix from. Overwrites the value of suffix if not None.

Optional, defaults to "default"

property suffix_separator: str: Character(s) to separate the state text and the suffix. Set to None for no separator.

Optional, defaults to None

property text: str: The current text displayed on the button. Setting this attribute automatically converts the value into a string.

Optional, defaults to ""

property text_anchor_alignment: tuple[Literal[None, 'l', 'm', 'r', 's'], Literal[None, 'a', 't', 'm', 's', 'b', 'd']]: Alignment of the textAnchor as (horizontal,vertical). Leave (one of) None to determine the anchor from text_x_position or text_y_position respectively. See https://pillow.readthedocs.io/en/stable/handbook/text-anchors.html#text-anchors for possible values, only accepts shorthands.

Optional, defaults to (None, None)

property text_mode: bool: If True, the element will display the set text, instead of the state. Use with care.

Optional, defaults to False

property text_x_position: int | Literal['l', 'm', 'r', 's']: Horizontal alignment of the text. Can be top, bottom or center, a Pillow textanchor (shorthand and longhand), a pssm dimensional string or an integer.

Optional, defaults to "center"

property text_y_position: int | Literal['a', 't', 'm', 's', 'b', 'd']: Vertical alignment of the text. Can be top, bottom or center, a Pillow textanchor (shorthand and longhand), a pssm dimensional string or an integer.

Optional, defaults to "center"

Compact

property entity: str: Required

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to None

property font_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property attribute_styles: attribute_stylesDict: Optional, defaults to []

property entity_attribute: str | None: Optional, defaults to None

property feedback_duration: duration: Optional, defaults to 0.75

property fit_text: bool: Optional, defaults to False

property font: Optional, defaults to "default"

property font_size: str | int | float: Optional, defaults to "H*0.036"

property margins: tuple[int, int, int, int]: Optional, defaults to 0

property multiline: bool: Optional, defaults to False

property outline_width: str | int | float: Optional, defaults to 1

property prefix_attribute: str | None: Optional, defaults to None

property prefix_separator: str: Optional, defaults to None

property radius: str | int | float: Optional, defaults to 0

property resize: bool | str | int | float: Optional, defaults to False

property state_colors: bool: Optional, defaults to False

property state_conditionals: bool: Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Optional, defaults to {}

property suffix_attribute: str | None: Optional, defaults to "default"

property suffix_separator: str: Optional, defaults to None

property text: str: Optional, defaults to ""

property text_anchor_alignment: tuple[Literal[None, 'l', 'm', 'r', 's'], Literal[None, 'a', 't', 'm', 's', 'b', 'd']]: Optional, defaults to (None, None)

property text_mode: bool: Optional, defaults to False

property text_x_position: int | Literal['l', 'm', 'r', 's']: Optional, defaults to "center"

property text_y_position: int | Literal['a', 't', 'm', 's', 'b', 'd']: Optional, defaults to "center"

List

entity, Required. The entity_id of the entity associated with this element.
background_color, Optional, defaults to None. Color of the element background.
font_color, Optional, defaults to "black". The color of the font
outline_color, Optional, defaults to None. Color of the elements outline.
hold_action, Optional, defaults to None. The function called when the element is held.
hold_release_action, Optional, defaults to None. The function called when the element is released from being held down.
tap_action, Optional, defaults to None. The function called when the element is tapped.
attribute_styles, Optional, defaults to []. Element styling as determined by the values of attributes.
entity_attribute, Optional, defaults to None. The entity’s attribute being shown as the element’s state.
feedback_duration, Optional, defaults to 0.75. Duration of the element’s feedback function
fit_text, Optional, defaults to False. Adjusts the font size automatically to make it fit.
font, Optional, defaults to "default". The path to the element’s font.
font_size, Optional, defaults to "H*0.036". The size of the font
margins, Optional, defaults to 0. The text margins.
multiline, Optional, defaults to False. Allows the button to try and fit its text over multiple lines.
outline_width, Optional, defaults to 1. The width of the outline of the background rectangle
prefix_attribute, Optional, defaults to None. Entity attribute to get the prefix from. Overwrites the value of prefix if not None.
prefix_separator, Optional, defaults to None. Character(s) to separate the state text and the prefix. Set to None for no separator
radius, Optional, defaults to 0. Corner radius of the encapsulating rectangle.
resize, Optional, defaults to False. Tracks the font_size and adjusts it to fit. The resize value updates and will be used as a starting point for the next update.
state_colors, Optional, defaults to False. Allows the element’s color configured state colors.
state_conditionals, Optional, defaults to False. The element will first treat the keys in the state_styles dict as possible conditions.
state_styles, Optional, defaults to {}. Dict mapping entity states (or entity attribute if set) to element properties.
suffix_attribute, Optional, defaults to "default". Entity attribute to get the suffix from. Overwrites the value of suffix if not None.
suffix_separator, Optional, defaults to None. Character(s) to separate the state text and the suffix. Set to None for no separator
text, Optional, defaults to "". The current text displayed on the button.
text_anchor_alignment, Optional, defaults to (None, None). Alignment of the textAnchor as (horizontal,vertical).
text_mode, Optional, defaults to False. If True, the element will display the set text, instead of the state. Use with care.
text_x_position, Optional, defaults to "center". Horizontal alignment of the text.
text_y_position, Optional, defaults to "center". Vertical alignment of the text.

class EntityTile¶

Version of the Tile Element linked to an entity.

The text and title Button are replaced with StateButtons, and hence the textProperties and titleProperties are set via here as well. state_styles can be defined via the appropriate property variable, or via the state_styles of the Tile itself.

Available element tiles are:

icon, title, text

Shorthand tile_layout values are:

vertical: "icon;title;text"
horizontal: "icon,[title;text]"

Available shorthand actions are:

generate: Generates the element’s image data.
update: Function to update an element via actions.

Element Properties

Full

property entity: str: Required. The entity_id of the entity associated with this element. Can be changed, but that will also mean the old entity is not linked anymore.

property accent_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Accent color to style child elements. Not inherently used in the layout itself, but can be used in child elements, to give them a uniform style Set a color_property of one to “accent” to do so.

Optional, defaults to "gray"

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Background color of the element. Automatically set to None if background_shape is used.

Optional, defaults to "white"

property foreground_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Foreground color to style child elements Additional color property for Layouts. Not inherently used in the layout itself, but can be used in child elements, to give them a uniform style. Set a color_property of one to “foreground” to do so.

Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the layout’s outline. Set to None to use no outline.

Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is held. Set to None to have nothing called. If set to a dict, the values for hold_action_data and hold_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is released from being held down. This function is only available on devices with the HOLD_RELEASE feature. Set to None to have nothing called. If set to a dict, the values for hold_release_action_data and hold_release_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is tapped. Set to None to have nothing called. If set to a dict, the values for tap_action_data and tap_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property attribute_styles: attribute_stylesDict: Element styling as determined by the values of attributes. This is somewhat advanced, and the conditions are very flexible. This may come at the cost of both performance and security, as it may enable executing random code (I am not sure, I am not a programmer. Please notify me if it is really bad).

Optional, defaults to []

property background_shape: Literal['circle', 'square', 'rounded_square', 'rounded_rectangle', 'octagon', 'hexagon', 'ADVANCED'] | None: The shape to apply to the button background. Keep in mind some square shapes won’t automatically fit the shape. The shape takes the background colour.

Optional, defaults to "default"

property badge_icon: mdi:icon | None: Icon to use as a badge for the Tile’s Icon element. Must be None or an mdi icon.

Optional, defaults to None

property badge_location: Literal['UR', 'LR', 'UL', 'LL']: The location of the badge. Can be Can be one of UR, LR, UL or LL (Upper Right, Lower Right, Upper Left, Lower Left). Also accepts the fully written strings, but will be set to the abbreviated location.

Optional, defaults to "UR"

property badge_settings: dict: Dict with settings to apply to the badge. background_color needs to be defined explicitly, otherwise it is automatically set to the background color or default color.

Optional, defaults to {}

property element_properties: dict[str, dict]: Dict with properties for each element. Accepts parsing colors. Use as nested dicts, the first key specifying the element tag, with the dict within denoting the properties to set.

Optional, defaults to {'icon': {'icon_attribute': 'icon'}, 'text': {}, 'title': {'entity_attribute': 'friendly_name'}}

property entity_attribute: str | bool: Optional entity attribute to use as state. Set to None to use entity state.

Optional, defaults to None

property feedback_duration: duration: Duration of the element’s feedback function The time an element will stay in ‘feedback state’, before returning to its normal state. Can be set to a string, which will be parsed to the right amount of seconds.

Optional, defaults to 0.75

property hide: tuple[str]: Elements that will be explicitly removed from the layout parsed from tile_layout. Set to None, or an empty iterable to hide nothing. Elements can also be hidden by simply omitting them from the tile_layout.

Optional, defaults to ()

property horizontal_sizes: _EltSizeDict: Horizontal sizes for the elements. Returns the default values when set to default, not ‘default’.

Optional, defaults to "default"

property icon: The current icon. Can be set to a str (either an mdi icon or image file), or a PIL image instance directly. If the latter, the image will still be treated as an image file i.e. any icon settings etc. are applied to it regardless (This does also mean you don’t need to worry about sizing, as that is also taken care of). Can also be set to None for no icon.

Optional, defaults to None

property outline_width: str | int | float: Width of the outline of the encompassing rectangle.

Optional, defaults to 0

property radius: str | int | float: Corner radius of the element’s background. Only applicable when no background shape is used, otherwise 0.

Optional, defaults to 0

property shape_settings: dict: Settings to apply to the tile background. background_color and outline_color/width are set from the properties if not present. If backgroundshape is ADVANCED, you are responsible for all settings yourself, as well as specifying the drawing method to use.

Optional, defaults to {}

property state_colors: bool: Allows the element’s color configured state colors. Only if the main color property is not defined in the dict for the state.

Optional, defaults to False

property state_conditionals: bool: The element will first treat the keys in the state_styles dict as possible conditions. The first condition to return true will be used to configure the element’s attributes. If none return True, it will check if the state is present as a key, and only then will use the default element_state if provided.

Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Dict mapping entity states (or entity attribute if set) to element properties. Applies the properties corresponding to the state that matched a key. You can also add a default key to use for undefined states. Some default trigger functions deal with the Unavailable and Unknown states, but these can be overwritten. If a key returns a string instead of a dict, the value is used to update the base attribute (i.e. set a new icon for Icon elements.).

Optional, defaults to {}

property tile_layout: Literal['vertical', 'horizontal'] | LayoutString: String used to set the layout. None if the layout was set directly.

Optional, defaults to "horizontal"

property title: The title text displayed on the above the Tile text. Set to None to not include it.

Optional, defaults to None

property vertical_sizes: _EltSizeDict: Vertical sizes for the elements. Returns the default values when set to default, not ‘default’.

Optional, defaults to "default"

Compact

property entity: str: Required

property accent_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Optional, defaults to "gray"

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to "white"

property foreground_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property attribute_styles: attribute_stylesDict: Optional, defaults to []

property background_shape: Literal['circle', 'square', 'rounded_square', 'rounded_rectangle', 'octagon', 'hexagon', 'ADVANCED'] | None: Optional, defaults to "default"

property badge_icon: mdi:icon | None: Optional, defaults to None

property badge_location: Literal['UR', 'LR', 'UL', 'LL']: Optional, defaults to "UR"

property badge_settings: dict: Optional, defaults to {}

property element_properties: dict[str, dict]: Optional, defaults to {'icon': {'icon_attribute': 'icon'}, 'text': {}, 'title': {'entity_attribute': 'friendly_name'}}

property entity_attribute: str | bool: Optional, defaults to None

property feedback_duration: duration: Optional, defaults to 0.75

property hide: tuple[str]: Optional, defaults to ()

property horizontal_sizes: _EltSizeDict: Optional, defaults to "default"

property icon: Optional, defaults to None

property outline_width: str | int | float: Optional, defaults to 0

property radius: str | int | float: Optional, defaults to 0

property shape_settings: dict: Optional, defaults to {}

property state_colors: bool: Optional, defaults to False

property state_conditionals: bool: Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Optional, defaults to {}

property tile_layout: Literal['vertical', 'horizontal'] | LayoutString: Optional, defaults to "horizontal"

property title: Optional, defaults to None

property vertical_sizes: _EltSizeDict: Optional, defaults to "default"

List

entity, Required. The entity_id of the entity associated with this element. Can be changed, but that will also mean the old entity is not linked anymore.
accent_color, Optional, defaults to "gray". Accent color to style child elements.
background_color, Optional, defaults to "white". Background color of the element. Automatically set to None if background_shape is used.
foreground_color, Optional, defaults to "black". Foreground color to style child elements
outline_color, Optional, defaults to None. Color of the layout’s outline.
hold_action, Optional, defaults to None. The function called when the element is held.
hold_release_action, Optional, defaults to None. The function called when the element is released from being held down.
tap_action, Optional, defaults to None. The function called when the element is tapped.
attribute_styles, Optional, defaults to []. Element styling as determined by the values of attributes.
background_shape, Optional, defaults to "default". The shape to apply to the button background. Keep in mind some square shapes won’t automatically fit the shape.
badge_icon, Optional, defaults to None. Icon to use as a badge for the Tile’s Icon element. Must be None or an mdi icon
badge_location, Optional, defaults to "UR". The location of the badge.
badge_settings, Optional, defaults to {}. Dict with settings to apply to the badge. background_color needs to be defined explicitly, otherwise it is automatically set to the background color or default color.
element_properties, Optional, defaults to {'icon': {'icon_attribute': 'icon'}, 'text': {}, 'title': {'entity_attribute': 'friendly_name'}}. Dict with properties for each element.
entity_attribute, Optional, defaults to None. Optional entity attribute to use as state. Set to None to use entity state.
feedback_duration, Optional, defaults to 0.75. Duration of the element’s feedback function
hide, Optional, defaults to (). Elements that will be explicitly removed from the layout parsed from tile_layout.
horizontal_sizes, Optional, defaults to "default". Horizontal sizes for the elements. Returns the default values when set to default, not ‘default’
icon, Optional, defaults to None. The current icon. Can be set to a str (either an mdi icon or image file), or a PIL image instance directly.
outline_width, Optional, defaults to 0. Width of the outline of the encompassing rectangle
radius, Optional, defaults to 0. Corner radius of the element’s background. Only applicable when no background shape is used, otherwise 0.
shape_settings, Optional, defaults to {}. Settings to apply to the tile background. background_color and outline_color/width are set from the properties if not present.
state_colors, Optional, defaults to False. Allows the element’s color configured state colors.
state_conditionals, Optional, defaults to False. The element will first treat the keys in the state_styles dict as possible conditions.
state_styles, Optional, defaults to {}. Dict mapping entity states (or entity attribute if set) to element properties.
tile_layout, Optional, defaults to "horizontal". String used to set the layout.
title, Optional, defaults to None. The title text displayed on the above the Tile text. Set to None to not include it.
vertical_sizes, Optional, defaults to "default". Vertical sizes for the elements. Returns the default values when set to default, not ‘default’

class PersonElement¶

Element displaying where a person is (i.e. the state of a person entity).

Takes all options except badge from the EntityTile.

Available element tiles are:

icon, title, text

Shorthand tile_layout values are:

vertical: "icon;title;text"
horizontal: "icon,[title;text]"

Available shorthand actions are:

generate: Generates the element’s image data.
update: Function to update an element via actions.

Element Properties

Full

property entity: str: Required. The entity_id of the entity associated with this element. Can be changed, but that will also mean the old entity is not linked anymore.

property accent_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Accent color to style child elements. Not inherently used in the layout itself, but can be used in child elements, to give them a uniform style Set a color_property of one to “accent” to do so.

Optional, defaults to "gray"

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Background color of the element. Automatically set to None if background_shape is used.

Optional, defaults to "white"

property foreground_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Foreground color to style child elements Additional color property for Layouts. Not inherently used in the layout itself, but can be used in child elements, to give them a uniform style. Set a color_property of one to “foreground” to do so.

Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the layout’s outline. Set to None to use no outline.

Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is held. Set to None to have nothing called. If set to a dict, the values for hold_action_data and hold_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is released from being held down. This function is only available on devices with the HOLD_RELEASE feature. Set to None to have nothing called. If set to a dict, the values for hold_release_action_data and hold_release_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is tapped. Set to None to have nothing called. If set to a dict, the values for tap_action_data and tap_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property attribute_styles: attribute_stylesDict: Element styling as determined by the values of attributes. This is somewhat advanced, and the conditions are very flexible. This may come at the cost of both performance and security, as it may enable executing random code (I am not sure, I am not a programmer. Please notify me if it is really bad).

Optional, defaults to []

property background_shape: Literal['circle', 'square', 'rounded_square', 'rounded_rectangle', 'octagon', 'hexagon', 'ADVANCED'] | None: The shape to apply to the button background. Keep in mind some square shapes won’t automatically fit the shape. The shape takes the background colour.

Optional, defaults to "default"

property badge_icon: mdi:icon | None: Icon to use as a badge for the Tile’s Icon element. Must be None or an mdi icon.

Optional, defaults to None

property badge_location: Literal['UR', 'LR', 'UL', 'LL']: The location of the badge. Can be Can be one of UR, LR, UL or LL (Upper Right, Lower Right, Upper Left, Lower Left). Also accepts the fully written strings, but will be set to the abbreviated location.

Optional, defaults to "UR"

property badge_settings: dict: Dict with settings to apply to the badge. background_color needs to be defined explicitly, otherwise it is automatically set to the background color or default color.

Optional, defaults to {}

property element_properties: dict[str, dict]: Dict with properties for each element. Accepts parsing colors. Use as nested dicts, the first key specifying the element tag, with the dict within denoting the properties to set.

Optional, defaults to {'icon': {'icon_attribute': 'entity_picture', 'icon_color': False, 'background_shape': None, 'background_color': None}}

property entity_attribute: str | bool: Optional entity attribute to use as state. Set to None to use entity state.

Optional, defaults to None

property feedback_duration: duration: Duration of the element’s feedback function The time an element will stay in ‘feedback state’, before returning to its normal state. Can be set to a string, which will be parsed to the right amount of seconds.

Optional, defaults to 0.75

property hide: tuple[str]: Elements that will be explicitly removed from the layout parsed from tile_layout. Set to None, or an empty iterable to hide nothing. Elements can also be hidden by simply omitting them from the tile_layout.

Optional, defaults to {'text'}

property horizontal_sizes: _EltSizeDict: Horizontal sizes for the elements. Returns the default values when set to default, not ‘default’.

Optional, defaults to "default"

property icon: The current icon. Can be set to a str (either an mdi icon or image file), or a PIL image instance directly. If the latter, the image will still be treated as an image file i.e. any icon settings etc. are applied to it regardless (This does also mean you don’t need to worry about sizing, as that is also taken care of). Can also be set to None for no icon.

Optional, defaults to None

property outline_width: str | int | float: Width of the outline of the encompassing rectangle.

Optional, defaults to 0

property radius: str | int | float: Corner radius of the element’s background. Only applicable when no background shape is used, otherwise 0.

Optional, defaults to 0

property shape_settings: dict: Settings to apply to the tile background. background_color and outline_color/width are set from the properties if not present. If backgroundshape is ADVANCED, you are responsible for all settings yourself, as well as specifying the drawing method to use.

Optional, defaults to {}

property state_colors: bool: Allows the element’s color configured state colors. Only if the main color property is not defined in the dict for the state.

Optional, defaults to False

property state_conditionals: bool: The element will first treat the keys in the state_styles dict as possible conditions. The first condition to return true will be used to configure the element’s attributes. If none return True, it will check if the state is present as a key, and only then will use the default element_state if provided.

Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Dict mapping entity states (or entity attribute if set) to element properties. Applies the properties corresponding to the state that matched a key. You can also add a default key to use for undefined states. Some default trigger functions deal with the Unavailable and Unknown states, but these can be overwritten. If a key returns a string instead of a dict, the value is used to update the base attribute (i.e. set a new icon for Icon elements.).

Optional, defaults to {}

property tile_layout: Literal['vertical', 'horizontal'] | LayoutString: String used to set the layout. None if the layout was set directly.

Optional, defaults to "vertical"

property title: The title text displayed on the above the Tile text. Set to None to not include it.

Optional, defaults to None

property vertical_sizes: _EltSizeDict: Vertical sizes for the elements. Returns the default values when set to default, not ‘default’.

Optional, defaults to "default"

property zone_badges: MappingProxyType: Icons used to represent which zone the person is in (i.e. the state of the entity). Shown as a badge.

Optional, defaults to {'default': None, 'home': 'mdi:home', 'not_home': 'mdi:home-off', 'unavailable': 'mdi:exclamation-thick', 'unknown': 'mdi:exclamation-thick'}

Compact

property entity: str: Required

property accent_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Optional, defaults to "gray"

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to "white"

property foreground_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property attribute_styles: attribute_stylesDict: Optional, defaults to []

property background_shape: Literal['circle', 'square', 'rounded_square', 'rounded_rectangle', 'octagon', 'hexagon', 'ADVANCED'] | None: Optional, defaults to "default"

property badge_icon: mdi:icon | None: Optional, defaults to None

property badge_location: Literal['UR', 'LR', 'UL', 'LL']: Optional, defaults to "UR"

property badge_settings: dict: Optional, defaults to {}

property element_properties: dict[str, dict]: Optional, defaults to {'icon': {'icon_attribute': 'entity_picture', 'icon_color': False, 'background_shape': None, 'background_color': None}}

property entity_attribute: str | bool: Optional, defaults to None

property feedback_duration: duration: Optional, defaults to 0.75

property hide: tuple[str]: Optional, defaults to {'text'}

property horizontal_sizes: _EltSizeDict: Optional, defaults to "default"

property icon: Optional, defaults to None

property outline_width: str | int | float: Optional, defaults to 0

property radius: str | int | float: Optional, defaults to 0

property shape_settings: dict: Optional, defaults to {}

property state_colors: bool: Optional, defaults to False

property state_conditionals: bool: Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Optional, defaults to {}

property tile_layout: Literal['vertical', 'horizontal'] | LayoutString: Optional, defaults to "vertical"

property title: Optional, defaults to None

property vertical_sizes: _EltSizeDict: Optional, defaults to "default"

property zone_badges: MappingProxyType: Optional, defaults to {'default': None, 'home': 'mdi:home', 'not_home': 'mdi:home-off', 'unavailable': 'mdi:exclamation-thick', 'unknown': 'mdi:exclamation-thick'}

List

entity, Required. The entity_id of the entity associated with this element. Can be changed, but that will also mean the old entity is not linked anymore.
accent_color, Optional, defaults to "gray". Accent color to style child elements.
background_color, Optional, defaults to "white". Background color of the element. Automatically set to None if background_shape is used.
foreground_color, Optional, defaults to "black". Foreground color to style child elements
outline_color, Optional, defaults to None. Color of the layout’s outline.
hold_action, Optional, defaults to None. The function called when the element is held.
hold_release_action, Optional, defaults to None. The function called when the element is released from being held down.
tap_action, Optional, defaults to None. The function called when the element is tapped.
attribute_styles, Optional, defaults to []. Element styling as determined by the values of attributes.
background_shape, Optional, defaults to "default". The shape to apply to the button background. Keep in mind some square shapes won’t automatically fit the shape.
badge_icon, Optional, defaults to None. Icon to use as a badge for the Tile’s Icon element. Must be None or an mdi icon
badge_location, Optional, defaults to "UR". The location of the badge.
badge_settings, Optional, defaults to {}. Dict with settings to apply to the badge. background_color needs to be defined explicitly, otherwise it is automatically set to the background color or default color.
element_properties, Optional, defaults to {'icon': {'icon_attribute': 'entity_picture', 'icon_color': False, 'background_shape': None, 'background_color': None}}. Dict with properties for each element.
entity_attribute, Optional, defaults to None. Optional entity attribute to use as state. Set to None to use entity state.
feedback_duration, Optional, defaults to 0.75. Duration of the element’s feedback function
hide, Optional, defaults to {'text'}. Elements that will be explicitly removed from the layout parsed from tile_layout.
horizontal_sizes, Optional, defaults to "default". Horizontal sizes for the elements. Returns the default values when set to default, not ‘default’
icon, Optional, defaults to None. The current icon. Can be set to a str (either an mdi icon or image file), or a PIL image instance directly.
outline_width, Optional, defaults to 0. Width of the outline of the encompassing rectangle
radius, Optional, defaults to 0. Corner radius of the element’s background. Only applicable when no background shape is used, otherwise 0.
shape_settings, Optional, defaults to {}. Settings to apply to the tile background. background_color and outline_color/width are set from the properties if not present.
state_colors, Optional, defaults to False. Allows the element’s color configured state colors.
state_conditionals, Optional, defaults to False. The element will first treat the keys in the state_styles dict as possible conditions.
state_styles, Optional, defaults to {}. Dict mapping entity states (or entity attribute if set) to element properties.
tile_layout, Optional, defaults to "vertical". String used to set the layout.
title, Optional, defaults to None. The title text displayed on the above the Tile text. Set to None to not include it.
vertical_sizes, Optional, defaults to "default". Vertical sizes for the elements. Returns the default values when set to default, not ‘default’
zone_badges, Optional, defaults to {'default': None, 'home': 'mdi:home', 'not_home': 'mdi:home-off', 'unavailable': 'mdi:exclamation-thick', 'unknown': 'mdi:exclamation-thick'}. Icons used to represent which zone the person is in (i.e. the state of the entity). Shown as a badge

class MediaPlayer¶

A element to show the state of a media player.

Highly configurable and stylable (In my opinion), but the default values should make it similar to the media player cards in the HA frontend. Any element properties passed (e.g. info_title_properties or duration_slider_properties) will only overwrite the keys passed, otherwise the default value is used. These also accepts the values background and foreground for color properties, which parses the appropriate color of the MediaPlayer to that property. Due to complexity, does not use the TileElement class yet, so it may be rewritten in the future. This is also why the documentation is different from other tiles.

Currently available tiles are: media_info, controls, duration, artwork and volume

Available shorthand actions are:

generate: Generates the element’s image data.
update: Function to update an element via actions.

Element Properties

Full

property entity: str: Required. The entity_id of the entity associated with this element. Can be changed, but that will also mean the old entity is not linked anymore.

property accent_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: The accent color to use. Can be used for the element colors by setting it’s value to ‘accent’.

Optional, defaults to "gray"

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the element background.

Optional, defaults to None

property foreground_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: The main color to use for the icon and text. Can be overwritten by iconSettings and buttonSettings respectively.

Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the layout’s outline. Set to None to use no outline.

Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is held. Set to None to have nothing called. If set to a dict, the values for hold_action_data and hold_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is released from being held down. This function is only available on devices with the HOLD_RELEASE feature. Set to None to have nothing called. If set to a dict, the values for hold_release_action_data and hold_release_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is tapped. Set to None to have nothing called. If set to a dict, the values for tap_action_data and tap_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property artwork_properties: dict: Proprerties for the artwork. Setting this does _not_ remove previously set properties. Color properties can be set to foreground or background to use the respective media player’s color.

Optional, defaults to {}

property attribute_styles: attribute_stylesDict: Element styling as determined by the values of attributes. This is somewhat advanced, and the conditions are very flexible. This may come at the cost of both performance and security, as it may enable executing random code (I am not sure, I am not a programmer. Please notify me if it is really bad).

Optional, defaults to []

property control_icon_properties: dict: Proprerties for _all_ the control icons. Setting this does _not_ remove previously set properties.

Optional, defaults to {'icon_color': 'foreground'}

property controls_layout: Literal['default'] | LayoutString: Layout string for the control buttons. default value is a row with control buttons, where the type of media playing determines which are shown.

Optional, defaults to "default"

property duration_buttons_properties: dict: Properties of the duration text (both total duration and passed play time). Allows parsing of color values.

Optional, defaults to {'fit_text': True, 'font_size': 0}

property duration_slider_properties: dict: Properties to style the slider in the duration section.

Optional, defaults to {'style': 'box', 'active_color': 'foreground'}

property duration_type: Literal['slider', 'text']: The way to display the duration. Use slider to show a slider progression and text, or text for just text.

Optional, defaults to "slider"

property feedback_duration: duration: Duration of the element’s feedback function The time an element will stay in ‘feedback state’, before returning to its normal state. Can be set to a string, which will be parsed to the right amount of seconds.

Optional, defaults to 0.75

property ff_time: float: The time media is fast forwarded with when pressing the fast forward button.

Optional, defaults to 30

property info_text_properties: dict: Properties of the text button. Allows parsing of color values.

Optional, defaults to {'font_color': 'foreground', 'entity_attribute': 'media_artist', 'fit_text': True, 'font_size': 0}

property info_title_properties: dict: Properties of the text button. Allows parsing of color values.

Optional, defaults to {'font_color': 'foreground', 'attribute_styles': 'default_attribute_styles', 'entity_attribute': 'media_artist', 'font': 'header', 'fit_text': True, 'font_size': 0}

property off_icon_properties: dict: Properties to style the turn off icon.

Optional, defaults to {'icon': 'mdi:power', 'background_shape': 'circle', 'background_color': 'foreground', 'icon_color': 'background'}

property outline_width: str | int | float: Width of the outline of the encompassing rectangle.

Optional, defaults to 0

property player_layout: Literal['default'] | LayoutString: Layout string to define the layout of the element. Default is ‘[artwork,[[media_info,turn_off];controls;volume]];duration’ when media is playing, else ‘[artwork,[media_info,turn_off]];None’.

Optional, defaults to "default"

property radius: str | int | float: Corner radius of the outlining rectangle.

Optional, defaults to 0

property rewind_time: float: The time media is fast forwarded with when pressing the fast forward button.

Optional, defaults to 30

property show: tuple[Literal['media_info', 'controls', 'duration', 'artwork', 'volume', 'turn_off']]: Media player elements to show. Can be set to all to show all elements, if present in the player_layout (So useful when working with custom layouts.).

Optional, defaults to ['media_info', 'controls', 'duration', 'artwork']

property state_colors: bool: Allows the element’s color configured state colors. Only if the main color property is not defined in the dict for the state.

Optional, defaults to False

property state_conditionals: bool: The element will first treat the keys in the state_styles dict as possible conditions. The first condition to return true will be used to configure the element’s attributes. If none return True, it will check if the state is present as a key, and only then will use the default element_state if provided.

Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Dict mapping entity states (or entity attribute if set) to element properties. Applies the properties corresponding to the state that matched a key. You can also add a default key to use for undefined states. Some default trigger functions deal with the Unavailable and Unknown states, but these can be overwritten. If a key returns a string instead of a dict, the value is used to update the base attribute (i.e. set a new icon for Icon elements.).

Optional, defaults to {}

property volume_icon: mdi:icon: Icon to use for the volume icon in the volume section. Use ‘state’ to use the default icons set by the volume level.

Optional, defaults to "state"

property volume_icon_properties: dict: Properties to style the icon in the volume section.

Optional, defaults to {'icon_color': 'foreground'}

property volume_slider_properties: dict: Properties to style the slider in the volume section.

Optional, defaults to {'style': 'box', 'active_color': 'foreground', 'outline_color': 'foreground'}

Compact

property entity: str: Required

property accent_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Optional, defaults to "gray"

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to None

property foreground_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property artwork_properties: dict: Optional, defaults to {}

property attribute_styles: attribute_stylesDict: Optional, defaults to []

property control_icon_properties: dict: Optional, defaults to {'icon_color': 'foreground'}

property controls_layout: Literal['default'] | LayoutString: Optional, defaults to "default"

property duration_buttons_properties: dict: Optional, defaults to {'fit_text': True, 'font_size': 0}

property duration_slider_properties: dict: Optional, defaults to {'style': 'box', 'active_color': 'foreground'}

property duration_type: Literal['slider', 'text']: Optional, defaults to "slider"

property feedback_duration: duration: Optional, defaults to 0.75

property ff_time: float: Optional, defaults to 30

property info_text_properties: dict: Optional, defaults to {'font_color': 'foreground', 'entity_attribute': 'media_artist', 'fit_text': True, 'font_size': 0}

property info_title_properties: dict: Optional, defaults to {'font_color': 'foreground', 'attribute_styles': 'default_attribute_styles', 'entity_attribute': 'media_artist', 'font': 'header', 'fit_text': True, 'font_size': 0}

property off_icon_properties: dict: Optional, defaults to {'icon': 'mdi:power', 'background_shape': 'circle', 'background_color': 'foreground', 'icon_color': 'background'}

property outline_width: str | int | float: Optional, defaults to 0

property player_layout: Literal['default'] | LayoutString: Optional, defaults to "default"

property radius: str | int | float: Optional, defaults to 0

property rewind_time: float: Optional, defaults to 30

property show: tuple[Literal['media_info', 'controls', 'duration', 'artwork', 'volume', 'turn_off']]: Optional, defaults to ['media_info', 'controls', 'duration', 'artwork']

property state_colors: bool: Optional, defaults to False

property state_conditionals: bool: Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Optional, defaults to {}

property volume_icon: mdi:icon: Optional, defaults to "state"

property volume_icon_properties: dict: Optional, defaults to {'icon_color': 'foreground'}

property volume_slider_properties: dict: Optional, defaults to {'style': 'box', 'active_color': 'foreground', 'outline_color': 'foreground'}

List

entity, Required. The entity_id of the entity associated with this element.
accent_color, Optional, defaults to "gray". The accent color to use. Can be used for the element colors by setting it’s value to ‘accent’.
background_color, Optional, defaults to None. Color of the element background.
foreground_color, Optional, defaults to "black". The main color to use for the icon and text. Can be overwritten by iconSettings and buttonSettings respectively.
outline_color, Optional, defaults to None. Color of the layout’s outline.
hold_action, Optional, defaults to None. The function called when the element is held.
hold_release_action, Optional, defaults to None. The function called when the element is released from being held down.
tap_action, Optional, defaults to None. The function called when the element is tapped.
artwork_properties, Optional, defaults to {}. Proprerties for the artwork. Setting this does _not_ remove previously set properties. Color properties can be set to foreground or background to use the respective media player’s color
attribute_styles, Optional, defaults to []. Element styling as determined by the values of attributes.
control_icon_properties, Optional, defaults to {'icon_color': 'foreground'}. Proprerties for _all_ the control icons. Setting this does _not_ remove previously set properties.
controls_layout, Optional, defaults to "default". Layout string for the control buttons.
duration_buttons_properties, Optional, defaults to {'fit_text': True, 'font_size': 0}. Properties of the duration text (both total duration and passed play time). Allows parsing of color values
duration_slider_properties, Optional, defaults to {'style': 'box', 'active_color': 'foreground'}. Properties to style the slider in the duration section
duration_type, Optional, defaults to "slider". The way to display the duration. Use slider to show a slider progression and text, or text for just text.
feedback_duration, Optional, defaults to 0.75. Duration of the element’s feedback function
ff_time, Optional, defaults to 30. The time media is fast forwarded with when pressing the fast forward button
info_text_properties, Optional, defaults to {'font_color': 'foreground', 'entity_attribute': 'media_artist', 'fit_text': True, 'font_size': 0}. Properties of the text button. Allows parsing of color values
info_title_properties, Optional, defaults to {'font_color': 'foreground', 'attribute_styles': 'default_attribute_styles', 'entity_attribute': 'media_artist', 'font': 'header', 'fit_text': True, 'font_size': 0}. Properties of the text button. Allows parsing of color values
off_icon_properties, Optional, defaults to {'icon': 'mdi:power', 'background_shape': 'circle', 'background_color': 'foreground', 'icon_color': 'background'}. Properties to style the turn off icon
outline_width, Optional, defaults to 0. Width of the outline of the encompassing rectangle
player_layout, Optional, defaults to "default". Layout string to define the layout of the element.
radius, Optional, defaults to 0. Corner radius of the outlining rectangle
rewind_time, Optional, defaults to 30. The time media is fast forwarded with when pressing the fast forward button
show, Optional, defaults to ['media_info', 'controls', 'duration', 'artwork']. Media player elements to show.
state_colors, Optional, defaults to False. Allows the element’s color configured state colors.
state_conditionals, Optional, defaults to False. The element will first treat the keys in the state_styles dict as possible conditions.
state_styles, Optional, defaults to {}. Dict mapping entity states (or entity attribute if set) to element properties.
volume_icon, Optional, defaults to "state". Icon to use for the volume icon in the volume section. Use ‘state’ to use the default icons set by the volume level.
volume_icon_properties, Optional, defaults to {'icon_color': 'foreground'}. Properties to style the icon in the volume section
volume_slider_properties, Optional, defaults to {'style': 'box', 'active_color': 'foreground', 'outline_color': 'foreground'}. Properties to style the slider in the volume section

class WeatherElement¶

A Weather Element.

Opens a forecast popup on click (if tap_action is not specified) with a forecast from the entity.

Tiles are condition (The condition icon), title (A statebutton which by default shows the friendly name, but is also hidden by default) and weather-data, which is a TileLayout holding all the weather_data.

Available element tiles are:

condition, title, weather-data

Shorthand tile_layout values are:

vertical: "[condition,title];weather-data"
horizontal: "[condition;title],weather-data"

Available shorthand actions are:

generate: Generates the element’s image data.
update: Function to update an element via actions.
show-forecast: Opens the forecast popup and, if forecast_update is ‘on_open’, will get new forecast data.

Element Properties

Full

property entity: str: Required. The entity_id of the entity associated with this element. Can be changed, but that will also mean the old entity is not linked anymore.

property accent_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Accent color to style child elements. Not inherently used in the layout itself, but can be used in child elements, to give them a uniform style Set a color_property of one to “accent” to do so.

Optional, defaults to "gray"

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the element background.

Optional, defaults to None

property foreground_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Foreground color to style child elements Additional color property for Layouts. Not inherently used in the layout itself, but can be used in child elements, to give them a uniform style. Set a color_property of one to “foreground” to do so.

Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the layout’s outline. Set to None to use no outline.

Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is held. Set to None to have nothing called. If set to a dict, the values for hold_action_data and hold_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is released from being held down. This function is only available on devices with the HOLD_RELEASE feature. Set to None to have nothing called. If set to a dict, the values for hold_release_action_data and hold_release_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is tapped. Set to None to have nothing called. If set to a dict, the values for tap_action_data and tap_action_map will be overwritten if the respective key is present.

Optional, defaults to "show-forecast"

property attribute_styles: attribute_stylesDict: Element styling as determined by the values of attributes. This is somewhat advanced, and the conditions are very flexible. This may come at the cost of both performance and security, as it may enable executing random code (I am not sure, I am not a programmer. Please notify me if it is really bad).

Optional, defaults to []

property condition_icons: dict: Icons that are used for weather conditions. Shorthand values for predefined sets are “mdi”,”meteocons”,”meteocons-outline”. A custom dict is made up of the following keys: “default”: specifies the default icon to use, if it cannot be found in the set of day time icons “day”: icons to use during daytime (i.e. when the state of the sun.sun entity is not ‘below_horizon’) “night”: icons to use during nighttime (when sun.sun state is ‘below_horizon’). If the condition is not present in the night time icons, the daytime icon is used as a fallback, or default if it is not in there either. “suffix”: optional suffix to append to all the icon values “prefix”: optional prefix to append to all the icon values.

Optional, defaults to "mdi"

property element_properties: dict[str, dict]: Dict with properties for each element. Accepts parsing colors. Use as nested dicts, the first key specifying the element tag, with the dict within denoting the properties to set.

Optional, defaults to {'condition': {}, 'title': {}, 'weather-data': {}}

property entity_attribute: str | bool: Optional entity attribute to use as state. Set to None to use entity state.

Optional, defaults to None

property feedback_duration: duration: Duration of the element’s feedback function The time an element will stay in ‘feedback state’, before returning to its normal state. Can be set to a string, which will be parsed to the right amount of seconds.

Optional, defaults to 0.75

property hide: tuple[str]: Elements that will be explicitly removed from the layout parsed from tile_layout. Set to None, or an empty iterable to hide nothing. Elements can also be hidden by simply omitting them from the tile_layout.

Optional, defaults to ['title']

property horizontal_sizes: dict[str, str | int | float]: Horizontal sizing of the tiles. Setting this will update from the current values, not overwrite it.

Optional, defaults to {'inner': 0, 'outer': 0}

property outline_width: str | int | float: Width of the outline of the encompassing rectangle.

Optional, defaults to 0

property radius: str | int | float: Corner radius of the outlining rectangle.

Optional, defaults to 0

property state_colors: bool: Allows the element’s color configured state colors. Only if the main color property is not defined in the dict for the state.

Optional, defaults to False

property state_conditionals: bool: The element will first treat the keys in the state_styles dict as possible conditions. The first condition to return true will be used to configure the element’s attributes. If none return True, it will check if the state is present as a key, and only then will use the default element_state if provided.

Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Dict mapping entity states (or entity attribute if set) to element properties. Applies the properties corresponding to the state that matched a key. You can also add a default key to use for undefined states. Some default trigger functions deal with the Unavailable and Unknown states, but these can be overwritten. If a key returns a string instead of a dict, the value is used to update the base attribute (i.e. set a new icon for Icon elements.).

Optional, defaults to {}

property tile_layout: str | None: String used to set the layout. None if the layout was set directly.

Optional, defaults to "vertical"

property time_format: str: The time format string to use when formatting the datetime of forecasts.

Optional, defaults to "%A"

property vertical_sizes: dict[str, str | int | float]: Vertical sizing of the tiles. Setting this will update from the current values, not overwrite it.

Optional, defaults to {'inner': 0, 'outer': 0}

property weather_data: list: The weather data to show along with the forecast icon.

Optional, defaults to ['temperature']

property weather_data_icons: dict[Literal['datetime', 'cloud_coverage', 'condition', 'humidity', 'temperature', 'apparent_temperature', 'dew_point', 'pressure', 'visibility', 'wind_gust_speed', 'wind_speed', 'ozone', 'uv_index', 'wind_bearing'], str]: Dict with values for the weather_data entries and their corresponding icons. Can be set using a default string value for a default dict (“mdi”, “meteocons”, “meteocons-outline”). Otherwise, a dict can be used mapping the data names to icons. This dict can hold a value for ‘defaults’ (which is one of the string defaults), which will be used as a default set of icons to use. Initially, mdi will be used if not present. Set this key to None to use no default icons. If present, the keys prefix and suffix will respectively be used for each value in the dict as a prefix and suffix (to i.e. easily set image extensions). Set a data names value to None to use no icon (Default for any values not present in the data dict).

Optional, defaults to "mdi"

property weather_data_layout: LayoutString: Layout of the weather-data TileLayout. Set to default to automatically make a vertical stack of the elements in weather_data, otherwise a layout needs to be set with each element mapping to a value in weather_data.

Optional, defaults to "default"

property weather_data_properties: dict[Literal['icon', 'data'], dict]: properties for _ALL_ tiles with weather data. Available elements (for element_properties) are icon and data.

Optional, defaults to {}

Compact

property entity: str: Required

property accent_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Optional, defaults to "gray"

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to None

property foreground_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to "show-forecast"

property attribute_styles: attribute_stylesDict: Optional, defaults to []

property condition_icons: dict: Optional, defaults to "mdi"

property element_properties: dict[str, dict]: Optional, defaults to {'condition': {}, 'title': {}, 'weather-data': {}}

property entity_attribute: str | bool: Optional, defaults to None

property feedback_duration: duration: Optional, defaults to 0.75

property hide: tuple[str]: Optional, defaults to ['title']

property horizontal_sizes: dict[str, str | int | float]: Optional, defaults to {'inner': 0, 'outer': 0}

property outline_width: str | int | float: Optional, defaults to 0

property radius: str | int | float: Optional, defaults to 0

property state_colors: bool: Optional, defaults to False

property state_conditionals: bool: Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Optional, defaults to {}

property tile_layout: str | None: Optional, defaults to "vertical"

property time_format: str: Optional, defaults to "%A"

property vertical_sizes: dict[str, str | int | float]: Optional, defaults to {'inner': 0, 'outer': 0}

property weather_data: list: Optional, defaults to ['temperature']

property weather_data_icons: dict[Literal['datetime', 'cloud_coverage', 'condition', 'humidity', 'temperature', 'apparent_temperature', 'dew_point', 'pressure', 'visibility', 'wind_gust_speed', 'wind_speed', 'ozone', 'uv_index', 'wind_bearing'], str]: Optional, defaults to "mdi"

property weather_data_layout: LayoutString: Optional, defaults to "default"

property weather_data_properties: dict[Literal['icon', 'data'], dict]: Optional, defaults to {}

List

entity, Required. The entity_id of the entity associated with this element.
accent_color, Optional, defaults to "gray". Accent color to style child elements.
background_color, Optional, defaults to None. Color of the element background.
foreground_color, Optional, defaults to "black". Foreground color to style child elements
outline_color, Optional, defaults to None. Color of the layout’s outline.
hold_action, Optional, defaults to None. The function called when the element is held.
hold_release_action, Optional, defaults to None. The function called when the element is released from being held down.
tap_action, Optional, defaults to "show-forecast". The function called when the element is tapped.
attribute_styles, Optional, defaults to []. Element styling as determined by the values of attributes.
condition_icons, Optional, defaults to "mdi". Icons that are used for weather conditions. Shorthand values for predefined sets are “mdi”,”meteocons”,”meteocons-outline”.
element_properties, Optional, defaults to {'condition': {}, 'title': {}, 'weather-data': {}}. Dict with properties for each element.
entity_attribute, Optional, defaults to None. Optional entity attribute to use as state. Set to None to use entity state.
feedback_duration, Optional, defaults to 0.75. Duration of the element’s feedback function
hide, Optional, defaults to ['title']. Elements that will be explicitly removed from the layout parsed from tile_layout.
horizontal_sizes, Optional, defaults to {'inner': 0, 'outer': 0}. Horizontal sizing of the tiles.
outline_width, Optional, defaults to 0. Width of the outline of the encompassing rectangle
radius, Optional, defaults to 0. Corner radius of the outlining rectangle
state_colors, Optional, defaults to False. Allows the element’s color configured state colors.
state_conditionals, Optional, defaults to False. The element will first treat the keys in the state_styles dict as possible conditions.
state_styles, Optional, defaults to {}. Dict mapping entity states (or entity attribute if set) to element properties.
tile_layout, Optional, defaults to "vertical". String used to set the layout.
time_format, Optional, defaults to "%A". The time format string to use when formatting the datetime of forecasts
vertical_sizes, Optional, defaults to {'inner': 0, 'outer': 0}. Vertical sizing of the tiles.
weather_data, Optional, defaults to ['temperature']. The weather data to show along with the forecast icon
weather_data_icons, Optional, defaults to "mdi". Dict with values for the weather_data entries and their corresponding icons.
weather_data_layout, Optional, defaults to "default". Layout of the weather-data TileLayout. Set to default to automatically make a vertical stack of the elements in weather_data, otherwise a layout needs to be set with each element mapping to a value in weather_data.
weather_data_properties, Optional, defaults to {}. properties for _ALL_ tiles with weather data. Available elements (for element_properties) are icon and data

class WeatherForecast¶

An element that shows the weather forecast of the connected entity using a stack of WeatherElement elements.

Does NOT accept Tile like layout strings, but does accept the same color properties. ForecastElements also accept a list of values for its color properties (foreground_color, accent_color, background_color, outline_color). Using a list will have the element cycle through the values, i.e. the first WeatherElement will parse the first value if it has a color property matching the shorthand. Then the next WeatherElement will parse the next value in the list, etc. Values are still cycled even if they’re not used in an element. So, for example, using background_color = ["black","white"] and foreground_color = ["white","black"], and element_properties = {"background_color": "background", "foreground_color": "foreground"} will mean the first WeatherElement has a white foreground_color and black background_color. The second one will have a black foreground_color and a white background_color, etc. Parsing color strings is should work without putting them in a list, but in case of using i.e. RGB values, it may be a bit finnicky. The best way to use these values is to already pass them as a nested list (i.e. pass [[100,100,50]] instead of [100,100,50]). Checks are in place to prevent this but better safe than sorry.

Due to the way the client is setup, the first forecast data cannot be retrieved before printing has started, so the element will initially show the default texts and icons. However the elements should update within the first few seconds, provided a connection to Home Assistant was successfully made.

Available shorthand actions are:

generate: Generates the element’s image data.
update: Function to update an element via actions.

Element Properties

Full

property entity: str: Required. The entity_id of the entity associated with this element. Can be changed, but that will also mean the old entity is not linked anymore.

property accent_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Accent color to style child elements. Not inherently used in the layout itself, but can be used in child elements, to give them a uniform style Set a color_property of one to “accent” to do so.

Optional, defaults to "gray"

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the element background.

Optional, defaults to "white"

property foreground_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Foreground color to style child elements Additional color property for Layouts. Not inherently used in the layout itself, but can be used in child elements, to give them a uniform style. Set a color_property of one to “foreground” to do so.

Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the layout’s outline. Set to None to use no outline.

Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is held. Set to None to have nothing called. If set to a dict, the values for hold_action_data and hold_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is released from being held down. This function is only available on devices with the HOLD_RELEASE feature. Set to None to have nothing called. If set to a dict, the values for hold_release_action_data and hold_release_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is tapped. Set to None to have nothing called. If set to a dict, the values for tap_action_data and tap_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property attribute_styles: attribute_stylesDict: Element styling as determined by the values of attributes. This is somewhat advanced, and the conditions are very flexible. This may come at the cost of both performance and security, as it may enable executing random code (I am not sure, I am not a programmer. Please notify me if it is really bad).

Optional, defaults to []

property element_properties: dict[str, dict]: Dict with properties for each element. Accepts parsing colors. Needs to be set using the set_element_properties method. Works a bit different that the normal behaviour, as element keys do not need to be specified (The properties are set the same for each WeatherElement).

Optional, defaults to {'background_color': 'background', 'foreground_color': 'foreground', 'accent_color': 'accent'}

property entity_attribute: str | bool: Optional entity attribute to use as state. Set to None to use entity state.

Optional, defaults to None

property feedback_duration: duration: Duration of the element’s feedback function The time an element will stay in ‘feedback state’, before returning to its normal state. Can be set to a string, which will be parsed to the right amount of seconds.

Optional, defaults to 0.75

property forecast_data: Literal['datetime', 'cloud_coverage', 'condition', 'humidity', 'temperature', 'apparent_temperature', 'dew_point', 'pressure', 'visibility', 'wind_gust_speed', 'wind_speed', 'ozone', 'uv_index', 'wind_bearing']: The forecast data to show. Works similarly to the WeatherElement weather_data. Available options for the entity can be determined by calling the get_forecasts action in Home Assistant for the element’s entity. Units for the forecast data are gathered from the entity’s attributes.

Optional, defaults to ['datetime', 'temperature', 'precipitation', 'precipitation_probability']

property forecast_type: Literal['daily', 'hourly', 'twice_daily']: The forecast type to show. Keep in mind Weather entities do not support all types.

Optional, defaults to "daily"

property horizontal_sizes: dict[str, str | int | float]: Horizontal sizing of the tiles. Setting this will update from the current values, not overwrite it.

Optional, defaults to {'inner': 0, 'outer': 0}

property num_forecasts: int: The number of forecasts to show.

Optional, defaults to 5

property orientation: Literal['horizontal', 'vertical']: Direction to stack the forecasts in. Either left to right (horizontal) or top to bottom (vertical).

Optional, defaults to "horizontal"

property outline_width: str | int | float: Width of the outline of the encompassing rectangle.

Optional, defaults to 0

property radius: str | int | float: Corner radius of the outlining rectangle.

Optional, defaults to 0

property skip_forecasts: int | Literal['now']: How many forecast entries to skip before using them to populate the elements. None is shorthand(ish) value for not skipping any. If set to now, any forecast whos datetime value is smaller than the datetime value of the current time will be omitted. Can be a negative integer, which means you’ll get the last x forecasts (i.e. setting it to -3 will mean only the last 3 of the returned forecasts are processsed). Does not perform checks when setting, to see if enough forecasts are left in combination with the value of num_forecasts.

Optional, defaults to 0

property state_colors: bool: Allows the element’s color configured state colors. Only if the main color property is not defined in the dict for the state.

Optional, defaults to False

property state_conditionals: bool: The element will first treat the keys in the state_styles dict as possible conditions. The first condition to return true will be used to configure the element’s attributes. If none return True, it will check if the state is present as a key, and only then will use the default element_state if provided.

Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Dict mapping entity states (or entity attribute if set) to element properties. Applies the properties corresponding to the state that matched a key. You can also add a default key to use for undefined states. Some default trigger functions deal with the Unavailable and Unknown states, but these can be overwritten. If a key returns a string instead of a dict, the value is used to update the base attribute (i.e. set a new icon for Icon elements.).

Optional, defaults to {}

property time_format: str: The time format string to use when formatting the datetime of forecasts.

Optional, defaults to "%A"

property update_interval: duration | int | float | None: interval between updates, if update_every is not None.

Optional, defaults to "1h"

property vertical_sizes: dict[str, str | int | float]: Vertical sizing of the tiles. Setting this will update from the current values, not overwrite it.

Optional, defaults to {'inner': 0, 'outer': 0}

Compact

property entity: str: Required

property accent_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Optional, defaults to "gray"

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to "white"

property foreground_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property attribute_styles: attribute_stylesDict: Optional, defaults to []

property element_properties: dict[str, dict]: Optional, defaults to {'background_color': 'background', 'foreground_color': 'foreground', 'accent_color': 'accent'}

property entity_attribute: str | bool: Optional, defaults to None

property feedback_duration: duration: Optional, defaults to 0.75

property forecast_data: Literal['datetime', 'cloud_coverage', 'condition', 'humidity', 'temperature', 'apparent_temperature', 'dew_point', 'pressure', 'visibility', 'wind_gust_speed', 'wind_speed', 'ozone', 'uv_index', 'wind_bearing']: Optional, defaults to ['datetime', 'temperature', 'precipitation', 'precipitation_probability']

property forecast_type: Literal['daily', 'hourly', 'twice_daily']: Optional, defaults to "daily"

property horizontal_sizes: dict[str, str | int | float]: Optional, defaults to {'inner': 0, 'outer': 0}

property num_forecasts: int: Optional, defaults to 5

property orientation: Literal['horizontal', 'vertical']: Optional, defaults to "horizontal"

property outline_width: str | int | float: Optional, defaults to 0

property radius: str | int | float: Optional, defaults to 0

property skip_forecasts: int | Literal['now']: Optional, defaults to 0

property state_colors: bool: Optional, defaults to False

property state_conditionals: bool: Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Optional, defaults to {}

property time_format: str: Optional, defaults to "%A"

property update_interval: duration | int | float | None: Optional, defaults to "1h"

property vertical_sizes: dict[str, str | int | float]: Optional, defaults to {'inner': 0, 'outer': 0}

List

entity, Required. The entity_id of the entity associated with this element.
accent_color, Optional, defaults to "gray". Accent color to style child elements.
background_color, Optional, defaults to "white". Color of the element background.
foreground_color, Optional, defaults to "black". Foreground color to style child elements
outline_color, Optional, defaults to None. Color of the layout’s outline.
hold_action, Optional, defaults to None. The function called when the element is held.
hold_release_action, Optional, defaults to None. The function called when the element is released from being held down.
tap_action, Optional, defaults to None. The function called when the element is tapped.
attribute_styles, Optional, defaults to []. Element styling as determined by the values of attributes.
element_properties, Optional, defaults to {'background_color': 'background', 'foreground_color': 'foreground', 'accent_color': 'accent'}. Dict with properties for each element. Accepts parsing colors. Needs to be set using the set_element_properties method.
entity_attribute, Optional, defaults to None. Optional entity attribute to use as state. Set to None to use entity state.
feedback_duration, Optional, defaults to 0.75. Duration of the element’s feedback function
forecast_data, Optional, defaults to ['datetime', 'temperature', 'precipitation', 'precipitation_probability']. The forecast data to show. Works similarly to the WeatherElement weather_data.
forecast_type, Optional, defaults to "daily". The forecast type to show. Keep in mind Weather entities do not support all types.
horizontal_sizes, Optional, defaults to {'inner': 0, 'outer': 0}. Horizontal sizing of the tiles.
num_forecasts, Optional, defaults to 5. The number of forecasts to show
orientation, Optional, defaults to "horizontal". Direction to stack the forecasts in. Either left to right (horizontal) or top to bottom (vertical)
outline_width, Optional, defaults to 0. Width of the outline of the encompassing rectangle
radius, Optional, defaults to 0. Corner radius of the outlining rectangle
skip_forecasts, Optional, defaults to 0. How many forecast entries to skip before using them to populate the elements. None is shorthand(ish) value for not skipping any.
state_colors, Optional, defaults to False. Allows the element’s color configured state colors.
state_conditionals, Optional, defaults to False. The element will first treat the keys in the state_styles dict as possible conditions.
state_styles, Optional, defaults to {}. Dict mapping entity states (or entity attribute if set) to element properties.
time_format, Optional, defaults to "%A". The time format string to use when formatting the datetime of forecasts
update_interval, Optional, defaults to "1h". interval between updates, if update_every is not None
vertical_sizes, Optional, defaults to {'inner': 0, 'outer': 0}. Vertical sizing of the tiles.

class EntityTimer¶

A tile based element for timer entities.

Provided tiles are ‘icon’, ‘title’, ‘timer’, ‘timer-slider’, ‘timer-countdown’ and ‘duration’. Depending on what you put into the tile_layout, you can display the time either via a slider or textually.

Available element tiles are:

icon, title, timer, timer-slider, timer-countdown, duration

Shorthand tile_layout values are:

horizontal: "icon,[title;timer]"
vertical: "icon;title;timer"

Available shorthand actions are:

generate: Generates the element’s image data.
update: Function to update an element via actions.
start-timer: Starts the timer and the connected timer entity
pause-timer: Pauses the timer and the connected entity
cancel-timer: Cancels the timer
toggle-timer: Toggles the timer between running and pausing

Element Properties

Full

property entity: str: Required. The entity_id of the entity associated with this element. Can be changed, but that will also mean the old entity is not linked anymore.

property accent_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Accent color to style child elements. Not inherently used in the layout itself, but can be used in child elements, to give them a uniform style Set a color_property of one to “accent” to do so.

Optional, defaults to "gray"

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the element background.

Optional, defaults to None

property foreground_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Foreground color to style child elements Additional color property for Layouts. Not inherently used in the layout itself, but can be used in child elements, to give them a uniform style. Set a color_property of one to “foreground” to do so.

Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Color of the layout’s outline. Set to None to use no outline.

Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is held. Set to None to have nothing called. If set to a dict, the values for hold_action_data and hold_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is released from being held down. This function is only available on devices with the HOLD_RELEASE feature. Set to None to have nothing called. If set to a dict, the values for hold_release_action_data and hold_release_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: The function called when the element is tapped. Set to None to have nothing called. If set to a dict, the values for tap_action_data and tap_action_map will be overwritten if the respective key is present.

Optional, defaults to None

property attribute_styles: attribute_stylesDict: Element styling as determined by the values of attributes. This is somewhat advanced, and the conditions are very flexible. This may come at the cost of both performance and security, as it may enable executing random code (I am not sure, I am not a programmer. Please notify me if it is really bad).

Optional, defaults to []

property element_properties: dict[str, dict]: Dict with properties for each element. Accepts parsing colors. Use as nested dicts, the first key specifying the element tag, with the dict within denoting the properties to set.

Optional, defaults to {'icon': {'icon_attribute': 'icon', 'icon_color': 'foreground', 'background_color': 'accent', 'background_shape': 'circle', 'tap_action': 'toggle-timer'}, 'timer-slider': {'style': 'box', 'inactive_color': 'accent', 'active_color': 'foreground', 'outline_color': None}, 'title': {'entity_attribute': 'friendly_name', 'text_xPosition': 'left', 'font': 'header'}, 'timer-countdown': {'text_xPosition': 'left'}}

property entity_attribute: str | bool: Optional entity attribute to use as state. Set to None to use entity state.

Optional, defaults to None

property feedback_duration: duration: Duration of the element’s feedback function The time an element will stay in ‘feedback state’, before returning to its normal state. Can be set to a string, which will be parsed to the right amount of seconds.

Optional, defaults to 0.75

property horizontal_sizes: dict[str, str | int | float]: Horizontal sizing of the tiles. Setting this will update from the current values, not overwrite it.

Optional, defaults to {'icon': 'r'}

property outline_width: str | int | float: Width of the outline of the encompassing rectangle.

Optional, defaults to 0

property radius: str | int | float: Corner radius of the outlining rectangle.

Optional, defaults to 0

property state_colors: bool: Allows the element’s color configured state colors. Only if the main color property is not defined in the dict for the state.

Optional, defaults to False

property state_conditionals: bool: The element will first treat the keys in the state_styles dict as possible conditions. The first condition to return true will be used to configure the element’s attributes. If none return True, it will check if the state is present as a key, and only then will use the default element_state if provided.

Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Dict mapping entity states (or entity attribute if set) to element properties. Applies the properties corresponding to the state that matched a key. You can also add a default key to use for undefined states. Some default trigger functions deal with the Unavailable and Unknown states, but these can be overwritten. If a key returns a string instead of a dict, the value is used to update the base attribute (i.e. set a new icon for Icon elements.).

Optional, defaults to {}

property tile_layout: str | None: String used to set the layout. None if the layout was set directly.

Optional, defaults to "horizontal"

property timer_type: Literal['slider', 'countdown', 'countdown_total']: The type of timer to show. Slider will show a slider type element that decreases. countdown shows the remaining time (and counts down). countdown_total shows the remaining time and the total time.

Optional, defaults to "slider"

property vertical_sizes: dict[str, str | int | float]: Vertical sizing of the tiles. Setting this will update from the current values, not overwrite it.

Optional, defaults to {'inner': 0, 'outer': 0}

Compact

property entity: str: Required

property accent_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Optional, defaults to "gray"

property background_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to None

property foreground_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A]: Optional, defaults to "black"

property outline_color: str | int | list | tuple[L, A] | tuple[R, G, B] | tuple[R, G, B, A] | None: Optional, defaults to None

property hold_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property hold_release_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property tap_action: str | Callable[[Element, InteractEvent, Any], Any] | None: Optional, defaults to None

property attribute_styles: attribute_stylesDict: Optional, defaults to []

property element_properties: dict[str, dict]: Optional, defaults to {'icon': {'icon_attribute': 'icon', 'icon_color': 'foreground', 'background_color': 'accent', 'background_shape': 'circle', 'tap_action': 'toggle-timer'}, 'timer-slider': {'style': 'box', 'inactive_color': 'accent', 'active_color': 'foreground', 'outline_color': None}, 'title': {'entity_attribute': 'friendly_name', 'text_xPosition': 'left', 'font': 'header'}, 'timer-countdown': {'text_xPosition': 'left'}}

property entity_attribute: str | bool: Optional, defaults to None

property feedback_duration: duration: Optional, defaults to 0.75

property horizontal_sizes: dict[str, str | int | float]: Optional, defaults to {'icon': 'r'}

property outline_width: str | int | float: Optional, defaults to 0

property radius: str | int | float: Optional, defaults to 0

property state_colors: bool: Optional, defaults to False

property state_conditionals: bool: Optional, defaults to False

property state_styles: mappingproxy[Literal['state'], dict[Literal['property'], Any]]: Optional, defaults to {}

property tile_layout: str | None: Optional, defaults to "horizontal"

property timer_type: Literal['slider', 'countdown', 'countdown_total']: Optional, defaults to "slider"

property vertical_sizes: dict[str, str | int | float]: Optional, defaults to {'inner': 0, 'outer': 0}

List

entity, Required. The entity_id of the entity associated with this element.
accent_color, Optional, defaults to "gray". Accent color to style child elements.
background_color, Optional, defaults to None. Color of the element background.
foreground_color, Optional, defaults to "black". Foreground color to style child elements
outline_color, Optional, defaults to None. Color of the layout’s outline.
hold_action, Optional, defaults to None. The function called when the element is held.
hold_release_action, Optional, defaults to None. The function called when the element is released from being held down.
tap_action, Optional, defaults to None. The function called when the element is tapped.
attribute_styles, Optional, defaults to []. Element styling as determined by the values of attributes.
element_properties, Optional, defaults to {'icon': {'icon_attribute': 'icon', 'icon_color': 'foreground', 'background_color': 'accent', 'background_shape': 'circle', 'tap_action': 'toggle-timer'}, 'timer-slider': {'style': 'box', 'inactive_color': 'accent', 'active_color': 'foreground', 'outline_color': None}, 'title': {'entity_attribute': 'friendly_name', 'text_xPosition': 'left', 'font': 'header'}, 'timer-countdown': {'text_xPosition': 'left'}}. Dict with properties for each element.
entity_attribute, Optional, defaults to None. Optional entity attribute to use as state. Set to None to use entity state.
feedback_duration, Optional, defaults to 0.75. Duration of the element’s feedback function
horizontal_sizes, Optional, defaults to {'icon': 'r'}. Horizontal sizing of the tiles.
outline_width, Optional, defaults to 0. Width of the outline of the encompassing rectangle
radius, Optional, defaults to 0. Corner radius of the outlining rectangle
state_colors, Optional, defaults to False. Allows the element’s color configured state colors.
state_conditionals, Optional, defaults to False. The element will first treat the keys in the state_styles dict as possible conditions.
state_styles, Optional, defaults to {}. Dict mapping entity states (or entity attribute if set) to element properties.
tile_layout, Optional, defaults to "horizontal". String used to set the layout.
timer_type, Optional, defaults to "slider". The type of timer to show.
vertical_sizes, Optional, defaults to {'inner': 0, 'outer': 0}. Vertical sizing of the tiles.