features.md

CustomUI Features

• Customizer component
• CustomUI panel
• Global Features
  • Hiding entities from default view tab (HA 0.62+)
  • Template attributes [New in 20170927]
  • Icon Color
  • Action name
• Features available for all domains
  • Context-aware attributes
  • Badges in state cards
  • Per entity theming (Requires HA 0.50+)
  • Secondary custom UI
• Features available for almost all domains
  • You can always show the last-changed text
• Features available for light, cover, climate, "plain", and "toggle" cards
  • You can hide the control altogether
  • You can add extra data below the entity name
  • Add badge to the state card
  • Confirmable controls
  • Custom controls
• Features available for light and cover domains only
  • If there is not enough horizontal space the mode is set by state_card_mode parameter
  • If the slider got moved to a new line it will be 200 px wide.
  • The slider behavior is controlled by slider_theme dictionary.
• Complete example

Customizer component

See instruction in a dedicated repository: https://github.com/andrey-git/home-assistant-customizer Provides the following features:

• Load CustomUI files (HA 0.53+)
• Register CustomUI panel (HA 0.52 and below).
• Hide CustomUI attributes in more-info (HA 0.50 - 0.52)
• Hide arbitrary attributes in more-info (Requires HA 0.50+)
• Dynamic customization.
• Set the width and number of UI columns (Requires CustomUI 20180112+)

CustomUI panel

Use it to set device name.

In HA 0.53+ is added automatically to configuration panel.

Global Features

Those features do not require setting custom_ui_state_card: state-card-custom-ui on any entity. Just loading is enough.

Hiding entities from default view tab

Requires HA 0.62+

If you don't have a default_view view defined you still hide some entities from the Home tab by setting hide_in_default_view: true attribute.

If applied to a View (a group with view: true) hide_in_default_view will hide everything under that view (not just the view group itself).

Apply hide_in_default_view: false to prevent a specific entity from being hidden even if it is part of another view with hide_in_default_view: true

Template attributes

You can set entity's attributes or state using JavaScript templates. See Templates for more info.

For example to show "Active" instead of "on" for binary sensor:

homeassistant:
  customize:
    binary_sensor.my_sensor:
      templates:
        state: if (state === 'on') return 'Active'; else return state;

This is very powerful feature that can do a lot of cool things, but it could also have performance implications.

Icon Color

Starting from version 2018-04-27 you can set an icon color by specifying icon_color attribute which was removed from core in HA 0.66

For example:

homeassistant:
  customize:
    light.bed_light:
      icon_color: green

The color could take any CSS color value. For example: #FFACAC, red, rgba(10, 20, 30, 0.5) etc.

Note that the color will be applied as-is and it won't be affected by the brightness attribute.h

Action name

Starting from version 2018-04-29 you change the displayed action name by specifying action_name attribute.

Action name is the button used to activate scenes and to execute non-interruptible scripts.

For example:

homeassistant:
  customize:
    scene.dark:
      action_name: Darken

Features available for all domains

Context-aware attributes

You can use context-aware attributes to give different names/attributes for the same entity in different groups, views, or devices. See context-aware.md

Badges in state cards

If you like badges, you can now put them in the state cards. This also works for domains that are usually not used as a badge. Lights for example. There are 4 ways to put badges in a state card.

1. Turn a single state card into a badge. Adjacent badges will clamp together to a single line.

homeassistant:
  customize_glob:
    "*.*":
      custom_ui_state_card: state-card-custom-ui  
    sensor.door_sensor:
      state_card_mode: badges
    sensor.yard_sensor:
      state_card_mode: badges

group:
  my_group:
    entities:
      - sensor.door_sensor
      - sensor.yard_sensor

2. Create a dedicated group of devices you want to display as badges and apply state_card_mode: badges to it. Note that this group must be in another group. The example below will show 2 sensors as badges in outer_group's card.

homeassistant:
  customize_glob:
    "*.*":
      custom_ui_state_card: state-card-custom-ui  
    group.inner_group:
      state_card_mode: badges

group:
  inner_group:
    entities:
      - sensor.door_sensor
      - sensor.yard_sensor
  outer_group:
    entities:
      - group.inner_group
      *all other devices of outer_group*

3. If you already have a group, part of which you want to display as badges inside another group - use badges_list to filter badge wannabe entities. In the previous example, if you wanted to show only sensor.door_sensor as a badge in outer_group:

...
    group.inner_group:
      state_card_mode: badges
      badges_list:
        - sensor.door_sensor
group:
  inner_group:
     ...
  outer_group:
    ...
...

4. Creating a dedicated group has a downside that the group will also show in the UI as whole in the default_view. To prevent that, you can make the group include itself. In the following example inner_group and outer_group are the same group:

homeassistant:
  customize_glob:
    "*.*":
      custom_ui_state_card: state-card-custom-ui  
    group.my_group:
      state_card_mode: badges

group:
  my_group:
    entities:
      - sensor.door_sensor
      - sensor.yard_sensor
      - group.my_group
      *all other devices of outer_group*

If you use this example as-is you will notice that all of your devices in the group appear both as regular state cards and as badges. To limit badges to the door/yard sensors only use badges_list from Example 2. To hide door/yard sensor cards (but leave them as badges) use the Context-aware hide attribute feature.
Full example:

homeassistant:
  customize_glob:
    "*.*":
      custom_ui_state_card: state-card-custom-ui  
    group.my_group:
      state_card_mode: badges
      badges_list:
        - sensor.door_sensor
        - sensor.yard_sensor
    sensor.door_sensor:
      group:
        group.my_group:
          hidden: true
    sensor.yard_sensor:
      group:
        group.my_group:
          hidden: true

group:
  my_group:
    entities:
      - sensor.door_sensor
      - sensor.yard_sensor
      - light.mylight
      - group.my_group

Per entity theming

Requires HA 0.50+

You can select per-entity theme from the list of defined themes

frontend:
  themes:
    green_example:
      paper-toggle-button-checked-button-color: green
light.yard:
  theme: green_example

Starting from version 2018-01-26 per-entity theming can also affect top-of-the-page badges.

Secondary customUI

If you would like to use your own state-card-custom-alarm.html for alarm_control_panel but still enjoy framework features of CustomUI, like theming, you can use state_card_custom_ui_secondary:

homeassistant:
  customize_glob:
    "*.*":
      custom_ui_state_card: state-card-custom-ui
    alarm_control_panel.alarm:
      state_card_custom_ui_secondary: state-card-custom_alarm

Features available for almost all domains.

The following is supported for all state cards except configurator

You can always show the last-changed text

Use show_last_changed: true

Note that if you use the extra_data_template below it will take precedence over show_last_changed

Features available for light, cover, climate, "plain", and "toggle" cards.

The next features are available for 4 types of cards:

• Light
• Cover
• Climate
• "Plain" i.e. card with icon, name, and state.
• "Toggle" i.e. card with icon, name, and toggle.

You can hide the control altogether

Use hide_control: true to hide the control (toggle / cover buttons) altogether.

You can add extra data below the entity name

Use extra_data_template to add extra data below the entity name. The format is a Templates. For example to show power consumption from the power_consumption attribute use:

extra_data_template: ${attributes.power_consumption}W

Use can add several lines by using an array:

extra_data_template:
  - ${attributes.power_consumption}W
  - ${attributes.temperature}C

Add badge to the state card

Instead of using a gray text below the entity name you can add a sensor-like badge. There are two ways to do that:

1. Specify a real sensor by entity ID:

extra_badge:
  entity_id: sensor.my_sensor

2. Make a fake sensor from entity's attribute:

extra_badge:
  attribute: power_consumption
  unit: W

If you use the first format, i.e. a real sensor, you can use context-aware theming on it.

In both cases you can specify a blacklist of badge "states", when you don't want to see the badge.

extra_badge:
  entity_id: sensor.my_sensor
  blacklist_states: 0

You can also provide a list of badges:

extra_badge:
  - entity_id: sensor.my_sensor1
    blacklist_states: 0
  - entity_id: sensor.my_sensor2
    blacklist_states: 'z'

Confirmable controls

Sometimes you don't want to flip a switch by mistake.

Use confirm_controls_show_lock to block the control and show a transparent lock icon over it. Tapping on the lock will open it for 5 seconds allowing to use the control. If you would like to prevent accidental flip without the visual lock hint, use confirm_controls instead.

Custom controls

You can replace the default control with another control by using control_element attribute.

For example:

switch.my:
  control_element: my-custom-switch-element

You can also use control_element: '' to show the state, like the "plain" card does.

Features available for light and cover domains only

If there is enough space the card will have icon+name on the left, optional slider in the middle and toggle on the right:

If there is not enough horizontal space the mode is set by state_card_mode parameter

state_card_mode value	description
break-slider-toggle	Move the slider and the toggle together to a second line.
single-line	Never use more than one line. Shrink the name and the slider.
break-slider	Move slider to second line. Leave toggle on the first line.
hide-slider	Hide the slider.
no-slider (default)	Never show the slider even if there is enough space.

If the slider got moved to a new line it will be 200 px wide.

Use stretch_slider attribute to make it stretch to all available space.

The slider behavior is controlled by slider_theme dictionary.

In that dictionary the following optional fields are available:

field	default	description
min	0	Minimum slider value
max	255 for light, 100 for cover	Maximum slider value
pin	False	Display numeric value when moving the slider
off_when_min	True	Whether to turn the light off when moving the slider to the minimum value if that value is not 0
report_when_not_changed	True	Whether to send the light-controlling command if the slider was returned to the initial position. I.e. you moved the slider and then changed your mind

Complete example

homeassistant:
  customize:
    light.bedroom:
      custom_ui_state_card: state-card-custom-ui
      state_card_mode: break-slider
      stretch_slider: true
      extra_data_template: "${attributes.power_consumption !== 0 ? (attributes.power_consumption + 'W') : ''}"
      hide_control: false
      show_last_changed: false
      theme: happy
      confirm_controls_show_lock: true
      slider_theme:
        min: 10
        max: 200
        pin: true
        off_when_min: false
        report_when_not_changed: false
      extra_badge:
        entity_id: sensor.my_sensor  # Will take precedence over attribute and unit below.
        attribute: power_consumption
        unit: W
        blacklist_states: 0

frontend:
  extra_html_url:
    - /local/custom_ui/state-card-custom-ui.html