Button Card Template Sync

Keep custom:button-card templates in YAML, while keeping your Lovelace dashboards editable in the Home Assistant UI.

Button Card Template Sync reads a folder of separate, individual button-card template files, merges them deterministically, validates inheritance, and writes the result to the top-level button_card_templates key of a storage-mode / UI dashboard.

It is built for people who like to edit their dashboards in the UI, but prefer their shared button-card templates neatly organised into files where they can be reviewed, copied, backed up, and versioned.

Highlights

• UI setup through Settings > Devices & services with a single entry per dashboard and template folder merge.
• One sync entry per template folder with its target UI dashboard.
• Manual sync button and button_card_template_sync.sync_templates service.
• Dry-run "safe" mode by default, so validation can run without writing anything.
• Backup-before-write system using Home Assistant Store under .storage/button_card_template_sync.
• Clear-backups button/service and bounded backup retention.
• Diagnostic sensors for status, template count, last sync time, and auto-sync state.
• Optional auto-sync schedule with polling and stability debounce: track changes in your templates folder, BTCS handles the rest!
• Guardrails for duplicate YAML keys, duplicate template names, missing inheritance references, inheritance cycles, and unexpected dashboard changes.

Safety Model

This integration is intentionally conservative because it writes to a dashboard.

On every sync, it:

1. Reads YAML files directly inside the configured template folder.
2. Validates the merged template map and inheritance graph.
3. Loads the target storage dashboard through Home Assistant runtime objects.
4. Builds a patched dashboard config in memory.
5. Verifies that only the top-level button_card_templates key would change.
6. Creates and verifies a backup before real writes, unless backup is disabled.
7. Saves through Home Assistant's dashboard storage object.
8. Reloads the saved dashboard and verifies every other top-level key is still unchanged.

That last check covers views, kiosk_mode, themes, layout settings, and future Home Assistant dashboard keys.

Installation

HACS

You can add this integration as a custom repository from HACS:

Manual HACS steps:

1. Open HACS > Integrations.
2. Choose Custom repositories.
3. Add https://github.com/bchevreau/button-card-template-sync.
4. Select category Integration.
5. Download Button Card Template Sync.
6. Restart Home Assistant.

Manual

Copy this folder:

custom_components/button_card_template_sync

to:

<home_assistant_config>/custom_components/button_card_template_sync

Then restart Home Assistant.

Requirements

• Home Assistant 2026.3.2 or newer.
• HACS 2.0.5 or newer, if installing through HACS.
• A storage-mode (UI) Lovelace dashboard.
• custom:button-card installed separately if your dashboard uses button-card cards.

This integration does not install button-card itself.

Setup

1. Create or locate an existing button-card templates folder inside your Home Assistant config directory, for example button_card_templates.
2. Put one or more .yaml or .yml template files directly inside that folder.
3. Go to Settings > Devices & services > Add integration or click this button:
4. Search for Button Card Template Sync or click
5. Pick the template folder and target storage-mode dashboard.
6. Keep Dry run enabled for the first sync.

Version 1 reads YAML files directly in the configured folder. It does not scan nested subfolders.

Each YAML file should contain a top-level mapping of template names:

base_card:
  show_icon: true
  show_name: true

room_light:
  template: base_card
  tap_action:
    action: toggle

On sync, the merged mapping is written to:

button_card_templates:
  ...

Entities

Each sync entry comes fully-packed with Home Assistant management entities:

• Buttons: Sync (launch a manual sync), Clear backups (delete all stored backups)
• Switches: Dry run (turn on safe mode), Auto-sync (track changes to the folder automatically), Backup before write (copy your dashboard each time before running the sync)
• Numbers: Poll interval (adjust the frequency of the changes' tracking system), Backup retention (how many total backup copies are saved)
• Sensors: Status of the last sync, Template count last merged, Last sync timestamp

Services

button_card_template_sync.sync_templates

Runs one or all configured sync entries and returns a response.

Optional fields:

• entry_id: limit the run to one config entry; leave out to process all configured dashboards
• dry_run: one-call override for the entry dry-run setting; options: true or false; leave out for current setting.
• backup: override the entry backup setting; options: true or false; leave out to use the entry setting.

button_card_template_sync.clear_backups

Clears stored dashboard backups for one entry or all entries.

Optional fields:

• entry_id: limit cleanup to one config entry; leave out to clear backups for all configured entries.

Backups

Backups are created only for real writes when backup-before-write is enabled. They are stored with Home Assistant's storage helper under .storage/button_card_template_sync and indexed per config entry.

The backup retention number controls how many backups are kept for each entry. Backups are not stored inside custom_components, so HACS updates will not remove them.

Auto-Sync

Auto-sync is disabled by default.

When enabled, the integration polls the configured template folder, waits until a changed folder signature is stable across consecutive polls, and then runs the same sync path as a manual sync. Dry-run, backup, validation, and post-write verification rules still apply.

Beta Status

This project is still in Beta. Please be gentle and let us know if you find bugs or issues!

Recommended safe first workflow:

• Start with a test dashboard (Optionally use the raw configuration editor to copy-paste your entire content into a duplicate).
• Keep Dry run enabled until diagnostics look right and run a few things. Status should change to "Dry run OK" if everything went well.
• Keep Backup before write enabled before you turn Dry run off.
• Use Auto-sync only after a successful manual sync is proven.