Entity definitions¶

Entities are configured in the entities section of the Flexible Horseshoe Card.

In most cases, the only required field is the Home Assistant entity ID. The card can then use metadata already available in Home Assistant, including the entity name, area, icon, unit, precision, state formatting, and localization.

A minimal entity definition can therefore remain very small:

1
2

entities:
  - entity: sensor.memory_use_percent

Where available, the card uses Home Assistant metadata automatically. Names, areas, states, numbers, and units follow the language and locale configured in Home Assistant.

You can override these defaults when needed. For example, you can provide a custom name or icon, change the number of decimals, display an attribute instead of the main state, or use a JavaScript template to calculate a dynamic value.

Basic usage¶

A basic definition points to a single entity:

1
2

entities:
  - entity: sensor.memory_use_percent

You can also define multiple entities. Layout sections such as states, names, areas, and icons refer to them by entity_index.

1
2
3
4
5
6
7

- type: custom:flex-horseshoe-card
  entities:
    - entity: sensor.dsmr_reading_electricity_currently_delivered
    - entity: sensor.dsmr_reading_phase_currently_delivered_l1
    - entity: sensor.dsmr_reading_phase_currently_delivered_l2
    - entity: sensor.dsmr_reading_phase_currently_delivered_l3
    - entity: sensor.dsmr_reading_electricity_currently_delivered

The first entry has index 0, the second has index 1, and so on.

Sparkline values as entities¶

A sparkline can make its statistics and active history settings available as regular card entities. Add only the values you want to use to entities, then refer to them by entity: or by their normal entity_index from states, names, icons, texts, or other layout items.

The entity ID starts with fhs_sparkline, followed by the sparkline id and the requested value:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

entities:
  - entity: sensor.temperature
  - entity: fhs_sparkline.temperature_history_min
  - entity: fhs_sparkline.temperature_history_avg
  - entity: fhs_sparkline.temperature_history_max
  - entity: fhs_sparkline.temperature_history_duration
  - entity: fhs_sparkline.temperature_history_bin_duration
  - entity: fhs_sparkline.temperature_history_aggregate_func

layout:
  sparklines:
    - id: temperature_history
      entity_index: 0
      # Remaining sparkline configuration

  states:
    - id: minimum
      entity: fhs_sparkline.temperature_history_min
      xpos: 20
      ypos: 85
    - id: average
      entity: fhs_sparkline.temperature_history_avg
      xpos: 50
      ypos: 85
    - id: maximum
      entity: fhs_sparkline.temperature_history_max
      xpos: 80
      ypos: 85

The available values are:

When a sparkline declares explicit series, insert the series ID before the value suffix. The default single-series names above remain unchanged:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

entities:
  - entity: sensor.temperature
  - entity: sensor.humidity
  - entity: fhs_sparkline.climate_today_avg
  - entity: fhs_sparkline.climate_yesterday_room_avg

layout:
  sparklines:
    - id: climate
      entity_index: 0
      series:
        - id: today
          entity_index: 0
        - id: yesterday_room
          entity_index: 1

The resulting names are fhs_sparkline.<sparkline_id>_<series_id>_<value>. The series ID is matched against the declared configuration, so underscores in that ID remain unambiguous. Each derived value uses the source entity and the statistics of its own series.

A direct entity: reference is independent of list order. Card templates can place these entries in default_entities so every template instance receives the local values without changing the indices of entities supplied by the card.

Flexible Horseshoe Card automatically connects these values to the source entity used by the matching sparkline. Units, number formatting, and More info actions therefore continue to use that source sensor. You do not configure a separate source index.

Duration and bin size use Home Assistant duration formatting. For example, a bin duration of 0.5 hours is displayed as a localized duration with zero hours and thirty minutes. A setting that does not apply to the active graph type is shown using Home Assistant's translated Unavailable state.

Entity metadata from Home Assistant¶

The card uses Home Assistant metadata wherever possible. This keeps the YAML concise and helps the card remain consistent with the rest of your dashboard.

The following values can usually be obtained automatically:

You usually do not need to repeat the name, unit, icon, or precision unless this card should display the entity differently.

Displaying an entity¶

You can override Home Assistant metadata directly in the entity definition:

1
2
3
4
5
6

entities:
  - entity: sensor.memory_use_percent
    decimals: 0
    icon: mdi:memory
    name: '5: RAM Usage'
    area: Hestia

This example uses a custom name, icon, area, and precision instead of relying entirely on the Home Assistant defaults.

Displaying an attribute¶

An entity definition can display an attribute instead of the main state. This is useful for entities that expose several related values, such as weather entities.

1
2
3
4
5
6
7

entities:
  - entity: weather.dark_sky
    attribute: temperature
    units: '°C'
    icon: mdi:temperature
    decimals: 1
    name: 'Temperature'

You can also define multiple attributes from the same entity as separate entries:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

- type: custom:flex-horseshoe-card
  entities:
    - entity: weather.zoefdehaas
      attribute: temperature
    - entity: weather.zoefdehaas
      attribute: humidity
    - entity: weather.zoefdehaas
      attribute: pressure
    - entity: sun.sun
      attribute: elevation
    - entity: sun.sun
      attribute: azimuth

Each entry receives its own entity_index, even when several entries refer to the same Home Assistant entity.

Overriding entity values¶

The card can use Home Assistant defaults automatically, but you can override them in the entities section:

1
2
3
4
5
6
7

- type: custom:flex-horseshoe-card
  entities:
    - entity: sensor.dsmr_reading_electricity_currently_delivered
      name: "Total"
      decimals: 2
      icon: mdi:fire
      area: house

Common reasons to override values include:

• using a shorter name on a compact card;
• displaying fewer or more decimals;
• choosing a card-specific icon;
• placing an entity under a different area label;
• giving an attribute its own name and unit.

Shared color stops¶

Define color_stops on an entity when several layout items should use the same thresholds and colors:

1
2
3
4
5
6
7
8

entities:
  - entity: sensor.temperature
    color_stops:
      colors:
        0: blue
        18: green
        25: orange
        30: red

A layout item uses these colors after selecting show.item_style: colorstop or show.item_style: colorstopgradient. Entity-level color stops remain inactive for items that do not select either mode. A color_stops definition on the layout item overrides the entity definition for that item.

Overriding entity formatting¶

v5.4.7-dev.7

The format option overrides the default Home Assistant formatting for an entity.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

- type: custom:flex-horseshoe-card
  entities:
    - entity: sensor.dsmr_reading_electricity_currently_delivered
      name: "Total"
      icon: mdi:fire
      area: house
      format:
        separator: false    # Remove the thousands separator
        decimals_min: 0     # Minimum number of decimals
        decimals_max: 2     # Maximum number of decimals

1
2
3
4
5
6
7
8
9

- type: custom:flex-horseshoe-card
  entities:
    - entity: sensor.dsmr_reading_electricity_currently_delivered
      name: "Total"
      icon: mdi:fire
      area: house
      format:
        raw_state_keep: true  # Keep the raw state without formatting
        raw_state_clean: true # Remove underscores from the raw state

1
2
3
4
5
6
7
8

- type: custom:flex-horseshoe-card
  entities:
    - entity: sensor.dsmr_reading_electricity_currently_delivered
      name: "Total"
      icon: mdi:fire
      area: house
      format:
        locale: 'nl-NL' # Force Dutch translations and formatting

Dynamic entity values¶

Some entity fields can use JavaScript templates. This allows parts of the entity definition to change in response to current entity states.

Use this when a name, icon, area, unit, or another supported value should be calculated dynamically instead of remaining fixed.

For example, the name can depend on the state of another entity:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

- type: custom:flex-horseshoe-card
  entities:
    - entity: sensor.memory_use_percent
      name: |
        [[[
          const name = entities[1].state === 'on'
            ? '11: One Bulb ON'
            : '11: One Bulb OFF';
          return name;
        ]]]
      tap_action:
        action: more-info

    - entity: light.livingroom_light_duo_left_light
      name: 'hall'
      icon: mdi:lightbulb
      tap_action:
        action: perform-action
        perform_action: light.toggle
        target:
          entity_id: light.livingroom_light_duo_left_light

Here, the first entity changes its displayed name according to whether the second entity is on.

Supported icon fields can also use templates:

1
2
3
4
5
6
7
8
9

entities:
  - entity: sensor.dsmr_reading_electricity_currently_delivered
    icon: |
      [[[
        const value = Number(state);
        return value >= 0.4
          ? 'mdi:flash'
          : 'mdi:flash-off';
      ]]]

Templates in the entities section use the same [[[ ... ]]] syntax as other JavaScript templates in the card.

For details about JavaScript templates, available variables, and reusable template variables, see the templating documentation.

Available entity options¶

Available entity format options¶

v5.4.7-dev.7

Icon options¶

When no icon is specified, the card uses the Home Assistant entity icon where possible.

You can override it with an MDI icon, external image, external SVG, or JavaScript template.

Actions and local controls¶

Entities support tap_action, hold_action, and double_tap_action using the current Home Assistant dashboard action format. An individual layout item can override the action configured on its entity. Flexible Horseshoe Card also supports ordered action lists, Companion-app haptic feedback, and browser-local number, select, and boolean inputs.

See Actions and Local Controls for the available actions and complete examples.

Entity layout elements¶

Defining an entity does not automatically display every part of it. The entities section defines the data source, while the layout sections determine what appears and where it is positioned.

For detailed configuration of areas, names, states, and icons, see Tools.

For translated names and states, localized units, state colors, and number formatting, see Localization.