TimeFlow Card

A beautiful, highly customizable time card for Home Assistant. Use it as a countdown to an upcoming date, a count-up timer since a past event, or a live view of Home Assistant, Alexa, and Google Home timers. It includes multiple layouts, progress-circle options, a visual editor, and built-in Jinja2 template support.

[![Home Assistant][ha_badge]][ha_link] [![HACS][hacs_badge]][hacs_link] [![GitHub Release][release_badge]][release] [![Buy Me A Coffee][bmac_badge]][bmac] ![downloads]

Table of contents

Installation Configuration Examples Styling Templates

Installation

HACS (Recommended)

Manual Installation

1. Download timeflow-card.js from the latest release.
2. Copy the file to your config/www/ directory.
3. Add the card to your resources: ```yaml resources:
   • url: /local/timeflow-card.js type: module ```

Configuration

This card offers a wide range of options to customize its appearance and behavior. target_date is the primary date field:

• In mode: count_down, target_date is the end date.
• In mode: count_up, target_date is the start or "since" date.

If timer_entity or smart-timer auto-discovery is used, timer data takes priority over date-based calculations.

Option	Type	Default	Description
style	string	classic	Card layout: classic, eventy, or classic-compact.
mode	string	count_down	Time mode: count_down or count_up.
target_date	string	null	Main date field. In count-down mode this is the target date. In count-up mode this is the start date. Supports ISO strings, entity IDs, and templates.
creation_date	string	null	Optional start date for count-down progress calculations. Supports ISO strings, entity IDs, and templates.
count_up_goal_date	string	null	Optional goal/end date for count-up progress. Supports ISO strings, entity IDs, and templates.
count_up_cycle	string / number	null	Optional repeating count-up cycle such as 30d, 12h, 24:00:00, or raw seconds. Supports templates.
timer_entity	string	null	Home Assistant timer, sensor, or input_datetime entity. Overrides date-based display logic.
auto_discover_alexa	boolean	false	Automatically discover Alexa timer entities from the Alexa Media Player integration.
auto_discover_google	boolean	false	Automatically discover Google Home timer entities from the HA Google Home integration.
title	string	auto	Card title. Falls back to an automatic title when omitted. Supports templates.
subtitle	string	null	Optional subtitle override. Supports templates.
subtitle_prefix	string	null	Text prepended to the generated subtitle, such as in or Only.
subtitle_suffix	string	null	Text appended to the generated subtitle, such as left or elapsed.
header_icon	string	null	Optional Material Design icon shown next to the title in all styles.
header_icon_color	string	null	Optional header icon color. Supports templates.
header_icon_background	string	null	Optional background color behind the header icon. Supports templates.
show_years	boolean	false	Show years in the elapsed or remaining time output.
show_months	boolean	false	Show months in the elapsed or remaining time output.
show_weeks	boolean	false	Show weeks in the elapsed or remaining time output.
show_days	boolean	true	Show days in the elapsed or remaining time output.
show_hours	boolean	true	Show hours in the elapsed or remaining time output.
show_minutes	boolean	true	Show minutes in the elapsed or remaining time output.
show_seconds	boolean	true	Show seconds in the elapsed or remaining time output.
compact_format	boolean	auto	Use compact unit formatting such as 2d 5h 30m. When unset, compact formatting is auto-enabled when 3 or more units are shown.
text_color	string	theme	Primary text color. Supports templates.
background_color	string	theme	Card background color. Supports templates.
progress_color	string	theme	Progress-circle color. Supports templates.
icon_size	number	100	Base progress circle size in pixels. Auto-scales with the card dimensions.
stroke_width	number	15	Thickness of the progress circle stroke.
progress_bg_stroke	string	#FFFFFF1A	Background track color for the progress circle.
progress_bg_opacity	number	theme	Background track opacity percentage from 0 to 100.
invert_progress	boolean	false	Start the progress circle full and subtract from it instead of filling it up.
width / height	string / number	null	Fixed card dimensions, for example "200px", "100%", or 180.
aspect_ratio	string	null	Aspect ratio for responsive sizing, for example "1/1" or "16/9".
expired_text	string	localized	Text shown when a countdown completes. Supports templates.
expired_animation	boolean	true	Enables the celebration animation when a countdown expires.
tap_action	object	auto	Tap action for the card. Timer entities default to more-info when no tap action is set.
hold_action	object	null	Hold action for the card.
double_tap_action	object	null	Double-tap action for the card.
card_mod	object	null	Advanced styling via card-mod integration.

Examples

🏠 Count-Up Since Move-In

Track elapsed time since a past event using mode: count_up. This example uses the classic-compact layout, an optional header icon, an inverted progress ring, and a count_up_goal_date so the circle has a meaningful end point. If you prefer a repeating ring instead, replace count_up_goal_date with count_up_cycle: 30d.

View YAML

type: custom:timeflow-card
style: classic-compact
mode: count_up
title: Time Since Move-In
subtitle_suffix: lived here
target_date: "2025-06-01T10:30:00"
count_up_goal_date: "2026-06-01T10:30:00"
show_years: false
show_months: false
show_weeks: false
show_days: true
show_hours: true
show_minutes: true
show_seconds: false
header_icon: mdi:home-heart
header_icon_color: "#6E4B2F"
header_icon_background: "rgba(110, 75, 47, 0.12)"
background_color: "#FFF8F1"
text_color: "#4A3828"
progress_color: "#C77D4E"
progress_bg_stroke: "#E8D6C5"
progress_bg_opacity: 100
invert_progress: true
stroke_width: 10

---

🗂️ Eventy Style

The eventy layout is the most compact style and now works cleanly with or without a header icon. If no header_icon is provided, the title shifts over automatically and the layout stays aligned.

View YAML

type: custom:timeflow-card
style: eventy
title: Next Bin Collection
target_date: sensor.next_bin_collection
show_years: false
show_months: false
show_weeks: false
show_days: true
show_hours: false
show_minutes: false
show_seconds: false
background_color: "#F3F7F2"
text_color: "#243026"
progress_color: "#5E8C61"
expired_animation: false

---

🗓️ Daily Agenda Countdown

This is a smart "Daily agenda" card. It automatically updates to show you what's next on your calendar for the day and elegantly hides the countdown when there's nothing scheduled.

Note: Remember to replace calendar.your_calendar_entity with your own calendar entity ID.

View YAML

type: custom:timeflow-card
title: >-
  {% set event = state_attr('calendar.your_calendar_entity', 'start_time') %} {%
  if event and (now().date() == as_datetime(event).date()) %}
    {{ state_attr('calendar.your_calendar_entity', 'message') }}
  {% else %}
    No Events Today
  {% endif %}
target_date: >-
  {% set event = state_attr('calendar.your_calendar_entity', 'start_time') %} {%
  if event and (now().date() == as_datetime(event).date()) %}
    {{ event }}
  {% else %}
    2000-01-01T00:00:00  # A past date to prevent the countdown
  {% endif %}
creation_date: "{{ now().replace(hour=0, minute=0, second=0, microsecond=0).isoformat() }}"
show_months: false
show_days: true
show_hours: true
show_minutes: true
show_seconds: false
background_color: "#075056"
text_color: "#E4EEF0"
progress_color: "#FF5B04"
expired_animation: false
expired_text: Enjoy Your Day!
stroke_width: 10
card_mod:
  style: |
    ha-card .title {
      font-size: 2.2rem;
    }
    ha-card .subtitle {
      font-size: 1.0rem;
    }

---

☀️ Daily Progress Tracker

Track the current day. The progress circle fills up as the day goes on, and the subtitle dynamically displays the percentage of the day that has passed.

View YAML

type: custom:timeflow-card
title: Today
subtitle: " {{ (now().hour / 24 * 100) | round() }}%"
target_date: >-
  {{ (now().replace(hour=23, minute=59,
  second=59)).strftime('%Y-%m-%dT%H:%M:%S') }}
creation_date: "{{ now().replace(hour=0, minute=0, second=0).strftime('%Y-%m-%dT%H:%M:%S') }}"
show_days: false
show_hours: true
show_minutes: true
show_seconds: true
aspect_ratio: 1/1
height: 180
icon_size: 60
text_color: "#424244"
background_color: "#FAFEFE"
progress_color: "#FB4E5B"
stroke_width: 6
card_mod:
  style:
    .: |
      ha-card .title {
        font-size: 1.2rem;
      }
      ha-card .subtitle {
        font-size: 2rem;
      }
    progress-circle$: |
      .progress-bg {
        stroke: #E5E6EA; /* Dark gray background track */
      }

---

🎂 Dynamic Birthday Countdown

A fully automated birthday countdown. It calculates the person's upcoming age and even changes its color scheme based on the birth month. Simply fill in the name and birthdate in the designated title, target_date, and text_color sections to personalize it for anyone.

View YAML

To customize for different people, you need to update the variables in three places:

1. In the title section - change these 4 variables: yaml {% set person_name = "John" %} {% set birth_year = 1989 %} {% set birthday_month = 10 %} {% set birthday_day = 31 %}
2. In the target_date section - change these 2 variables: yaml {% set birthday_month = 10 %} {% set birthday_day = 31 %}
3. In the text_color section - change these 2 variables: yaml {% set birthday_month = 10 %} {% set birthday_day = 31 %}

type: custom:timeflow-card
title: >-
  {% set person_name = "John" %}
  {% set birth_year = 1989 %}
  {% set birthday_month = 10 %}
  {% set birthday_day = 31 %}
  {% set current_date = now() %}
  {% set this_year_birthday = current_date.replace(month=birthday_month, day=birthday_day, hour=0, minute=0, second=0, microsecond=0) %}
  {% if current_date > this_year_birthday %}
    {% set next_birthday = this_year_birthday.replace(year=this_year_birthday.year + 1) %}
  {% else %}
    {% set next_birthday = this_year_birthday %}
  {% endif %}
  {% set age = next_birthday.year - birth_year %}
  {{ person_name }}'s {{ age }}{{ 
    'st' if age % 10 == 1 and age % 100 != 11 else
    'nd' if age % 10 == 2 and age % 100 != 12 else
    'rd' if age % 10 == 3 and age % 100 != 13 else
    'th'
  }} Birthday

target_date: >-
  {% set birthday_month = 10 %}
  {% set birthday_day = 31 %}
  {% set current_date = now() %}
  {% set this_year_birthday = current_date.replace(month=birthday_month, day=birthday_day, hour=0, minute=0, second=0, microsecond=0) %}
  {% if current_date > this_year_birthday %}
    {% set next_birthday = this_year_birthday.replace(year=this_year_birthday.year + 1) %}
  {% else %}
    {% set next_birthday = this_year_birthday %}
  {% endif %}
  {{ next_birthday.isoformat() }}

creation_date: >-
  {% set current_date = now() %}
  {% set start_of_year = current_date.replace(month=1, day=1, hour=0, minute=0, second=0, microsecond=0) %}
  {{ start_of_year.isoformat() }}

show_days: true
show_hours: true
show_minutes: true
show_seconds: false

text_color: >-
  {% set birthday_month = 10 %}
  {% set birthday_day = 31 %}
  {% set current_date = now() %}
  {% set this_year_birthday = current_date.replace(month=birthday_month, day=birthday_day, hour=0, minute=0, second=0, microsecond=0) %}
  {% if current_date > this_year_birthday %}
    {% set next_birthday = this_year_birthday.replace(year=this_year_birthday.year + 1) %}
  {% else %}
    {% set next_birthday = this_year_birthday %}
  {% endif %}
  {% set days_until = (next_birthday - current_date).days %}
  {% if days_until == 0 %}
    #FF6B6B
  {% elif days_until <= 7 %}
    #4ECDC4
  {% elif days_until <= 30 %}
    #45B7D1
  {% else %}
    #96CEB4
  {% endif %}

background_color: "#2C3150"
progress_color: "#D0CFCF"
aspect_ratio: 4/2
stroke_width: 6

card_mod:
  style: |
    ha-card .title {
      font-size: 2.2rem;
    }
    ha-card .subtitle {
      font-size: 2.0rem;
    }

---

🌅 Automatic Sunrise & Sunset Card

A fully automatic countdown to the next sunrise or sunset. It dynamically