Skip to content

Installation

Jump to bottom
wallenium edited this page Aug 1, 2026 · 1 revision

Installation

This guide covers HACS installation, manual installation, resource registration, cache clearing, restarts, and the most common first-run problems.

Install with HACS

Step 1 - Add the repository

  1. Open HACS.
  2. Add a custom repository: git: /wallenium/HA-menstrual-cycle.
  3. Category: Integration.

Step 2 - Install the integration

  1. Search for Menstruation Cycle.
  2. Install it.
  3. Restart Home Assistant when prompted.

Step 3 - Add the integration in Home Assistant

  1. Open Settings → Devices & Services.
  2. Click Add Integration.
  3. Search for Menstruation Cycle.
  4. Create the first profile with a friendly name and icon.

Step 4 - Add a dashboard card

After the restart, the integration registers its card resources automatically. Add a manual card with:

type: custom:menstruation-cycle-card
entity: sensor.anna
title: Cycle Overview
show_editor: true
show_fertile_period: true
calendar_edit_enabled: true

Step 5 - Add the daily refresh automation

Import or recreate /examples/daily_recalculate_days_until_next_start.yaml so date-based values such as days_until_next_start stay current.

alias: Menstruation Cycle - Daily Recalculate days_until_next_start
trigger:
  - platform: time
    at: "00:00:05"
action:
  - service: menstruation_cycle.refresh_cycle_model
    data: {}

Manual installation (without HACS)

  1. Copy /home/runner/work/HA-menstrual-cycle/HA-menstrual-cycle/custom_components/menstruation_cycle to your Home Assistant config directory as /config/custom_components/menstruation_cycle.
  2. Restart Home Assistant.
  3. Open Settings → Dashboards → Resources and register these JavaScript module resources:
Resource Type
/menstruation_cycle/menstruation-cycle-card.js JavaScript module
/menstruation_cycle/menstruation-cycle-card-compact.js JavaScript module
/menstruation_cycle/menstruation-cycle-compact-status-card.js JavaScript module
/menstruation_cycle/menstruation-cycle-history-card-row.js JavaScript module
/menstruation_cycle/menstruation-cycle-heatmap-card.js JavaScript module
/menstruation_cycle/menstruation-calendar-card.js JavaScript module
/menstruation_cycle/menstruation-countdown-timer.js JavaScript module
/menstruation_cycle/menstruation-product-inventory-card.js JavaScript module
/menstruation_cycle/menstruation-statistics-card.js JavaScript module

Optional shared helper resource if you want to load it explicitly:

Optional helper Type
/menstruation_cycle/menstruation-icons.js JavaScript module
  1. Add the integration under Settings → Devices & Services.
  2. Add one profile per tracked person.
  3. Add cards to your dashboard.

Screenshots and visual references

Main dashboard example

HA Menstruation Cycle dashboard

Heatmap example

Heatmap example

Theme examples

Light theme example Dark theme example

Restart procedures

Use a full Home Assistant restart after:

  • installing the integration
  • copying files manually into custom_components
  • updating card files manually
  • changing dashboard resources

A browser-only refresh is not enough for backend changes.

Browser cache clearing tips

If cards still show an old frontend after an upgrade:

  • refresh the page with cache bypass once
  • fully close and reopen the Home Assistant tab
  • clear the app or browser cache if you use the HA Companion app
  • confirm that the old resource URL is not still registered in dashboard resources

Common setup issues and solutions

Problem Likely cause Fix
Integration not listed in HACS Custom repo not added correctly Re-add git: /wallenium/HA-menstrual-cycle as an Integration repository
Cards do not appear Missing resource registration or stale cache Restart HA, verify resources, then clear browser cache
Custom element doesn't exist Wrong card type or missing JS resource Confirm the exact custom: type and resource URL
Services are missing Integration not loaded yet Restart HA and verify the integration is configured
Sensor stays unavailable Profile setup incomplete or entity renamed Reopen the integration and check the created sensor entity IDs
Manual install works partly but not fully Some resources were skipped Register all 9 card resources listed above
Old card still used after update Browser cached prior JS bundle Force reload or clear cache

First-run checklist

  • Integration installed
  • Home Assistant restarted
  • Profile created
  • Sensor entity confirmed
  • Daily refresh automation added
  • At least one dashboard card added
  • Cache cleared if the frontend looks outdated

Clone this wiki locally