Timer Bar Card

Use the modifications option to change the card's style dynamically as time passes. You can filter modifications using elapsed (time passed) or remaining (time left). Filters can be percentages (e.g., 40%) or durations (e.g., 0:00:10).

Note: All matching modifications are applied, and the last one in the list takes precedence. To ensure styles override correctly as time progresses, list elapsed modifications in increasing order or remaining modifications in decreasing order.

type: custom:timer-bar-card
entities:
  - timer.alarm
modifications:
  - elapsed: 40%
    bar_foreground: orange
    active_icon: mdi:fire
    bar_height: 12px
  - elapsed: 70%
    bar_foreground: red
    active_icon: mdi:fire-alert

Most integrations require additional configuration so the card can identify the timer's format. To make the card work, you must identify an entity that provides information about the timer's state and timing.

Key concepts:

• Active State: The state(s) used to indicate a timer is running (e.g., active, on).
• Guess Mode: If enabled (guess_mode: true), the card attempts to guess when the timer is active instead of relying on an explicit active_state.
• Time Properties: You must provide enough information for the card to calculate progress. This usually involves providing at least two of: start_time, end_time, or duration. If an integration provides a remain_time attribute, you can use that combined with active_state.

If you are not using HACS, follow these steps to install the card manually in Home Assistant:

1. Download timer-bar-card.js from the latest release.
2. Move the file to your Home Assistant config/www folder.
3. Ensure Advanced Mode is enabled in your Home Assistant user profile.
4. Navigate to Configuration -> Lovelace Dashboards -> Resources.
5. Add a new resource with the path /local/timer-bar-card.js and set the type to JS module.
6. Refresh your page or restart Home Assistant.

# Note: This is a conceptual representation of the file move
mv timer-bar-card.js /path/to/homeassistant/config/www/

If you are developing a custom Lovelace card and want to include the timer bar functionality, install it via NPM:

npm install --save lovelace-timer-bar-card

Important: To avoid conflicts with the timer-bar-card-entity-row element, you must register the element using a unique tag name via window.customElements.define.

import { fillConfig, TimerBarEntityRow } from 'lovelace-timer-bar-card/src/timer-bar-entity-row';

// Assign a unique tag name to avoid conflicts
window.customElements.define('my-card-timer-bar-entity-row', TimerBarEntityRow);

// Use the element in your render function
const config = fillConfig({
    // extra customization on top of default config
});

return html`<my-card-timer-bar-entity-row
              .config=${config} .hass=${hass}
            ></my-card-timer-bar-entity-row>`;

If you have the Mushroom Card collection installed, you can enable a Mushroom-like appearance.

To use this mode:

1. Use entity (singular) instead of entities (plural).
2. Add the mushroom: key.

Under the mushroom: key, you can provide options compatible with Mushroom cards, such as layout, color, primary_info, secondary_info, icon_type, icon_color, and fill_container.

type: custom:timer-bar-card
entity: switch.my_switch
duration:
  fixed: '00:10:00'
invert: true
bar_direction: rtl
bar_width: 60%
mushroom:
  layout: vertical
  color: green

The card displays Home Assistant timers with minimal configuration. For standard Home Assistant timer entities, you only need to provide a list of entities under the entities key.

type: custom:timer-bar-card
entities:
  - timer.alarm
  - timer.alarm_two
  - timer.alarm_three

The easiest way to install Timer Bar Card is through the Home Assistant Community Store (HACS).

Available via HACS

To use the Mushroom-inspired layout, include a mushroom object in your card configuration. This enables specific layout options and styling compatible with Mushroom-style interfaces. When using Mushroom mode with a single entity, the card renders a timer-bar-mushroom-row.

type: timer-bar-card
entity: timer.my_timer
mushroom:
  layout: horizontal
  primary_info: name
  secondary_info: state
  icon_type: icon

You can use the modifications array to dynamically change the card's configuration based on the timer's progress. This allows you to change icons, colors, or other settings when certain time thresholds are met.

Supported triggers:

• remaining: Triggers when the remaining time is less than or equal to a value. Supports duration strings (e.g., '10m') or percentage strings (e.g., '25%').
• elapsed: Triggers when the elapsed time is greater than or equal to a value. Supports duration strings (e.g., '1h') or percentage strings (e.g., '50%').

Note: The older greater_than or greater_than_eq syntax is deprecated and will throw an error.

modifications: [
  {
    remaining: '10%',
    icon: 'mdi:alert',
    bar_foreground: 'red'
  },
  {
    elapsed: '50%',
    bar_height: '12px'
  }
]

The card attempts to synchronize the browser's clock with the Home Assistant server clock to ensure accurate timer progress.

• To show warnings: Set sync_issues: 'show'. If a significant discrepancy is detected between the Home Assistant last_changed timestamp and the local time, a warning message will appear: Detected sync issues: Home Assistant clock is [X]s [ahead of/behind] app time.
• To auto-fix: Set sync_issues: 'fix'. The card will attempt to calculate a _browserClockCorrection to align the local timer progress with the server's state.

The timer-bar-card can be configured in two primary modes: using a single entity or a list of entities.

• Single Entity Mode: Provide an entity key. If mushroom configuration is present, it renders using the Mushroom style. Otherwise, it uses the standard entity row style.
• Multiple Entities Mode: Provide an entities array. You can use a header_entity to display a title at the top of the card. You can also use show_empty to define what text is displayed when no entities match the configured filter.

Note: You cannot define both entity and entities in the same configuration.