Animations¶

The Flexible Horseshoe Card supports several forms of animation and dynamic visual behavior.

State-based animations are configured in the card’s animations section. When an entity or attribute reaches a configured state, the card applies styles or animations to selected layout items.

The card can also use standard CSS animations. You can use built-in animation names, define custom @keyframes, or add JavaScript templates to styles when the animation should change dynamically.

These options serve different purposes:

State-based animations and JavaScript templates¶

The card offers more than one way to create dynamic visual behavior.

Use the animations section for simple state matching, such as on, off, home, not_home, or another fixed state. This works well for applying predefined CSS animations, changing icon colors, or applying a known set of styles when a state matches.

Use JavaScript templates for more complex logic. Templates are better suited to numeric thresholds, calculated values, multiple conditions, dynamic icons, dynamic colors, or logic that depends on several entities.

These approaches are complementary. Choose the one that best matches the complexity of the condition.

State-based animations¶

The animations section is optional. Use it when a layout item should change after an entity reaches a specific state.

A state-based animation has three parts:

1. the entity that triggers the animation;
2. the state that must match;
3. the layout items that receive the new styles.

1
2
3
4
5
6
7
8

animations:
  entity.1:
    - state: 'on'
      circles:
        - animation_id: 10
          styles:
            - fill: var(--theme-gradient-color-08)
            - animation: jello 1s ease-in-out both

In this example, entity.1 refers to the second entity in the entities list. When that entity is on, the card applies the styles to the circle with animation_id: 10.

An animation can also use a fixed entity ID, for example entity.fhs_sparkline.temperature_history_avg. This is useful for a local entity supplied through a card template because its final list position does not matter.

Animation trigger options¶

When the entity definition uses an attribute, the attribute value becomes the animation trigger.

Animation target options¶

An animation target identifies the layout item to update and the styles to apply.

By default, the previous animation style is cleared before the new one is applied. Use reuse: true when the next state should build on the previous animation styles.

For example, an on state can set a circle color, while the off state preserves that color and only adds a zoom-out animation.

Predefined animations¶

The card includes several predefined CSS animation names. Use them with the CSS animation property inside a styles entry.

Many animations also benefit from a suitable transform-origin:

1
2
3

styles:
  - animation: jello 1s ease-in-out both
  - transform-origin: center

Example: state-based animation¶

The following example animates a circle and changes an icon color when the second entity changes state.

 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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

- type: 'custom:flex-horseshoe-card'
  entities:
    - entity: sensor.memory_use_percent
    - entity: light.1st_floor_hall_light
  animations:
    entity.1:
      - state: 'on'
        circles:
          - animation_id: 10
            styles:
              - fill: var(--theme-gradient-color-08)
              - opacity: 0.9
              - animation: jello 1s ease-in-out both
              - transform-origin: center
        icons:
          - animation_id: 0
            styles:
              - fill: black;
      - state: 'off'
        circles:
          - animation_id: 10
            reuse: true
            styles:
              - transform-origin: center
              - animation: zoomOut 1s ease-out both
        icons:
          - animation_id: 0
            styles:
              - fill: var(--primary-text-color)
  layout:
    icons:
      - id: 0
        animation_id: 0
        xpos: 50
        ypos: 55
        entity_index: 1
        icon_size: 3.5
        styles:
          - color: white
    circles:
      - id: 0
        animation_id: 0
        xpos: 50
        ypos: 50
        radius: 35
        styles:
          - fill: var(--primary-background-color)
      - id: 1
        animation_id: 10
        xpos: 50
        ypos: 50
        radius: 30
        entity_index: 1
        styles:
          - fill: var(--primary-background-color)

In this example:

• entity.1 watches the second entity;
• state: 'on' applies a fill color and starts the jello animation;
• state: 'off' starts zoomOut;
• animation_id: 10 connects the animation block to the second circle;
• animation_id: 0 connects the icon animation to the icon layout item.

Dynamic animations with JavaScript templates¶

JavaScript templates can also control animation behavior.

Use them when the animation depends on a numeric value, threshold, calculated result, or logic that is more complex than a fixed state match.

For example, an item can flash when its entity value exceeds a threshold:

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

horseshoes:
  - entity_index: 0
    xpos: 50
    ypos: 50
    radius: 40
    horseshoe_state:
      width: 12
      styles:
        - animation: |
            [[[
              const value = Number(state);
              return value >= 0.3
                ? 'flash 1s ease-in-out 3'
                : 'none';
            ]]]

Templates can also be stored in variables and reused:

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

variables:
  flashAnimation: |
    [[[
      const value = Number(state);
      return value >= 0.3
        ? 'flash 1s ease-in-out 3'
        : 'none';
    ]]]

layout:
  horseshoes:
    - entity_index: 0
      horseshoe_state:
        width: 12
        styles:
          - animation: |
              [[[ return variables['flashAnimation']; ]]]

For template syntax and available variables, see the templating page.

Dynamic icons with JavaScript templates¶

Entity icons can also change dynamically. This is usually configured in the entities section with a JavaScript template.

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';
      ]]]

Use this approach when the icon depends on a value or on logic that is easier to express in JavaScript.

For simple fixed states, the animations section can also change icon styling, such as its fill color.

Custom CSS animations¶

You can define your own CSS animations with standard @keyframes.

Choose a unique animation name, define the matching keyframes, and use that name in a styles entry.

The following example defines a custom stroke animation and applies it to a circle:

 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
29
30
31
32
33
34
35
36
37
38
39
40
41

- type: 'custom:flex-horseshoe-card'
  entities:
    - entity: sensor.memory_use_percent
    - entity: light.1st_floor_hall_light
    - entity: light.gledopto

  animations:
    entity.2:
      - state: 'on'
        circles:
          - animation_id: 3
            styles:
              - fill: var(--theme-gradient-color-03);
              - stroke-width: 2;
              - stroke: var(--primary-background-color);
              - opacity: 0.9;
              - stroke-dasharray: 94;
              - stroke-dashoffset: 1000;
              - animation: stroke 2s ease-out forwards;

        icons:
          - animation_id: 1
            styles:
              - fill: black;

      - state: 'off'
        circles:
          - animation_id: 3
            styles:
              - fill: var(--primary-background-color);
              - opacity: 0.7;
        icons:
          - animation_id: 1
            styles:
              - fill: var(--primary-text-color);
  # The @keyframes stroke runs the stroke animation for the second lightbulb, entity light.gledopto
  style: |
    ha-card {
      box-shadow: var(--theme-card-box-shadow);
    }
    @keyframes stroke { to { stroke-dashoffset: 0; } }

Card-level styling and animations¶

Animations can be combined with the card’s top-level styles section.

Use card-level styles for backgrounds, images, transitions, and other properties that affect the card container itself.

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

- type: 'custom:flex-horseshoe-card'
  entities:
    - entity: sensor.memory_use_percent
    - entity: light.1st_floor_hall_light

  styles:
    - background-color: rgba(20, 20, 20, 0.05);
    - background-image: url('/local/images/backgrounds/pollen-background-hd-3x1.png');
    - background-size: cover;
    - background-position: center;
    - background-repeat: no-repeat;
    - overflow: hidden;

Dynamic card styles¶

The top-level styles section can also contain JavaScript templates. Use them when a card-level style should respond to an entity state.

The following example changes the card background color based on the state of the first entity:

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

- type: 'custom:flex-horseshoe-card'
  entities:
    - entity: sensor.memory_use_percent
    - entity: light.1st_floor_hall_light

  styles:
    - background-color: |
        [[[
          const value = Number(state);
          return value >= 5
            ? 'var(--error-color);'
            : 'var(--primary-text-color);';
        ]]]
    - transition: background-color 1s ease-in-out;

JavaScript templates are evaluated dynamically and can respond during card updates.

For more information about template syntax, variables, and reusable template values, see the templating page.

Choosing the right method¶

External animation resources¶

The predefined animations are based on common CSS animation patterns. These resources can help when creating custom effects:

• CSS animations for beginners
• Animate.css
• Animista