HA Menstruation Cycle is a Home Assistant custom integration for tracking cycle history, showing cycle phases, and powering Lovelace dashboards with interactive menstrual-cycle cards.
It combines a Home Assistant integration, per-profile sensors, local data storage, and a frontend card set so households can keep the setup inside Home Assistant instead of spreading data across separate tools. The project supports multiple profiles, visual dashboards, product usage tracking, symptom logging, and export workflows.
- HACS-ready Home Assistant integration with UI-based setup
- Multiple profiles for shared households
- Interactive cards for cycle entry, calendar views, history, heatmaps, timers, and statistics
- Services for history management, symptom logging, exports, inventory workflows, and automations
- Automatic frontend resource registration when installed through the integration
- Local-first storage inside Home Assistant
- Open HACS and add the custom repository
git: /wallenium/HA-menstrual-cycle. - Install Menstruation Cycle, then add the integration under Settings → Devices & Services.
- Create a profile with a friendly name, restart Home Assistant, and add
custom:menstruation-gauge-cardto a dashboard. - Optional but recommended: import or recreate the daily refresh automation from
/examples/daily_recalculate_days_until_next_start.yaml.
For manual installation, extra cards, service examples, and troubleshooting, use the wiki pages below.
custom:menstruation-cycle-card has been removed. Update existing Lovelace YAML dashboards to use custom:menstruation-gauge-card instead.
Start here: Documentation Hub
Detailed guides:
This project is a convenience and visualization tool. It is not a medical device and must not be used as a reliable standalone method for contraception, conception planning, diagnosis, or safety-critical decisions.
Before using it in a shared household or for sensitive automations:
- treat predictions as approximations
- use automations only with explicit agreement from the affected people
- keep health, privacy, and backup considerations in mind
Read the full disclaimer in Disclaimer.
The integration now supports stage-aware onboarding and forecast confidence gating:
- pre_menarche – educational mode before the first period. Deterministic period/ovulation predictions are suppressed.
- early_menarche – learning phase after the first period when history is sparse/irregular. Forecasts are shown as broader possible windows with low confidence by default.
- established_cycle – standard cycle forecasting. If data quality is still too low, read-only display logic can temporarily downgrade to learning-phase behavior.
- Pre-menarche: no precise cycle-day claims; emphasis is on neutral tracking/supportive messaging.
- Early menarche: low-data users get uncertainty-aware windows (for example “possible period window”) and ovulation-day precision is withheld until data quality thresholds are met.
- Established cycle: prior behavior is retained unless confidence gates detect insufficient quality (too few valid cycles, high variability, or too few recent logs).
High-precision outputs are only shown when all required checks pass:
- minimum valid cycle count
- acceptable cycle variability bounds
- sufficient recent log activity
Otherwise the integration degrades to low-confidence window output and suppresses precise ovulation claims.
You can change the onboarding stage at any time in Settings → Devices & Services → Menstruation Cycle → Configure (onboarding_stage option).
The custom:menstruation-support-card provides age-appropriate, practical education and low-anxiety support for pre-/early-menarche users. It has no effect on forecast logic — it is a UI-only card.
| Module | Description |
|---|---|
| 🗓️ School-day helper reminders | Configurable, discreet reminder presets: kit check, drink water, comfort check-in, rest cue |
| 📖 Glossary | Plain-language definitions for cycle, ovulation, and spotting, with optional "learn more" expansion |
| 🔵 Cycle phases graphic | Abstract SVG donut chart of period / follicular / ovulation / luteal phases with legend and ARIA description |
| 🧼 Hygiene how-to cards | Step-by-step guides for washing period underwear and using a period cup (basics) |
| 💛 Reassurance cards | Short "Is this normal?" cards covering irregular timing, flow variation, and spotting, each with a gentle escalation prompt |
- Shown by default in
pre_menarcheandearly_menarchemodes. - Hidden by default in
established_cyclemode; set the internal_showInEstablishedflag or use a conditional card to display it when desired.
Reminders are rendered as a settings panel inside the card. Each preset can be toggled on/off and assigned a preferred time. School-day-only reminders are labelled accordingly. Quiet hours can be enabled to suppress reminders between configurable start and end times.
Note: The card renders reminder previews only. To send actual notifications, connect the reminder state to a Home Assistant automation using the notification service of your choice.
All content is for educational purposes only and must not be used as medical advice. Each content module includes a visible disclaimer. Users are encouraged to follow the instructions provided with their hygiene products and to consult a clinician for medical questions.
All user-facing strings in the Young Girls Support card use i18n keys (ygs_*). Translations are provided for English (🇬🇧), German (🇩🇪), Swedish (🇸🇪), French (🇫🇷), and Spanish (🇪🇸). To add or improve a translation, edit the corresponding file in custom_components/menstruation_cycle/www/translations/.
- The cycle phases SVG includes
role="img",aria-label, and a hidden<desc>element for screen readers. - Non-colour-only meaning: every phase has a text label in the legend alongside its colour dot.
- Toggle controls use visible focus styles.
- Reduced-motion: any future animations must respect
prefers-reduced-motion; the current SVG graphic is static.
The integration now includes an optional Cycle Dashboard sidebar page for a fast daily workflow.
- Open Settings → Devices & Services → Menstruation Cycle → Configure.
- Enable Show Cycle Dashboard in sidebar.
- (Optional) Set Prefer Cycle Dashboard as start page as a preference flag for setups that support default-page behavior.
If the sidebar toggle is disabled, existing cards and views continue to work unchanged.
- Use Edit dashboard to:
- show/hide cards
- reorder cards (up/down)
- toggle discreet mode
- optionally set display name/pronouns for the My Info mini-card
- Preferences are stored per user and profile.
- Young mode (
pre_menarche/early_menarche): simpler default layout with discreet mode enabled. - General mode (
established_cycle): richer default layout with more insight cards. - Users can reset back to mode defaults at any time from Edit mode.
- Discreet mode uses more neutral wording in overview content.
- Sensitive cards can be hidden individually.
- My Info card is optional and can stay hidden.
| Language | Status |
|---|---|
| 🇬🇧 English | ✅ 100% |
| 🇩🇪 German | ✅ 100% |
| 🇸🇪 Swedish | ✅ 100% |
| 🇫🇷 French | 🟡 96% – Seeking volunteers |
| 🇪🇸 Spanish | 🟡 95% – Seeking volunteers |
Template files for Swedish, French, and Spanish are already in place. See Translation Section for instructions on how to contribute a translation.
Feedback, ideas, bug reports, edge cases, and pull requests are welcome. If you want to improve documentation, add cards, refine services, or help with testing, please open an issue or PR.
AI was used to help draft parts of the code and English wording, while the project idea and implementation direction remain human-authored.