https://github.com/ngocjohn/lunar-phase-card
🌘 Custom card for tracking Moon phases
https://github.com/ngocjohn/lunar-phase-card
custom-card homeassistant lovelace lunar lunar-phases moon moon-phase
Last synced: about 2 months ago
JSON representation
🌘 Custom card for tracking Moon phases
- Host: GitHub
- URL: https://github.com/ngocjohn/lunar-phase-card
- Owner: ngocjohn
- License: mit
- Created: 2024-07-21T13:43:21.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-01-03T01:47:18.000Z (5 months ago)
- Last Synced: 2025-03-29T07:02:30.273Z (about 2 months ago)
- Topics: custom-card, homeassistant, lovelace, lunar, lunar-phases, moon, moon-phase
- Language: TypeScript
- Homepage: https://ngocjohn.is-a.dev/lunar-phase-card/
- Size: 93.5 MB
- Stars: 101
- Watchers: 1
- Forks: 17
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[![hacs][hacs-default]][hacs-default-link] [![hacs][hacs-validate]][hacs-validate-link] ![total-downloads] ![latest-downloads] [![community-forum][forum-badge]][forum-url] [![buy_me_a_coffee][bmac-badge]][bmac-link]
# 🌘 Lunar Phase Card
##
This is a Lovelace custom card for Home Assistant that provides detailed information about the current phase of the moon. This card leverages precise astronomical calculations to deliver accurate lunar data, making it a valuable addition for those interested in astronomy, astrology, or just tracking the moon's phases.
## Table of contents
Table of contents
- [Overview](#Lunar-Phase-Card)
- [Features](#features)
- [Installation](#installation)
- [HACS Installation](#hacs-installation)
- [Manual Installation](#manual-installation)
- [Configuration](#configuration)
## Features
- **Current Lunar Phase Display:** Shows the current phase of the moon.
- **Detailed Lunar Information:** Provides additional details about the lunar cycle.
- **Customizable:** Easily customizable to fit your dashboard's theme.
- **Responsive Design:** Works well on both desktop and mobile devices.
- **Custom Latitude and Longitude Configuration:** Offers the possibility to configure custom latitude and longitude for precise lunar data.
- **Specific Date Lunar Information:** Option to display the moon information for a specific date.
- **Multilingual Support**: The card includes various translations, making it accessible in multiple languages.
### Supported Localization
The following languages are supported in this project
| Language Code | Name | Native Name |
| ------------- | ---------------------- | ---------------------- |
| `ca` | Catalan | Català |
| `cs` | Czech | Čeština |
| `da` | Danish | Dansk |
| `de` | German | Deutsch |
| `en` | English | English |
| `es` | Spanish | Español |
| `fr` | French | Français |
| `id` | Indonesian | Bahasa Indonesia |
| `it` | Italian | Italiano |
| `lt` | Lithuanian | Lietuvių |
| `nl` | Nederlands | Dutch |
| `pl` | Polish | Polski |
| `pt` | Portuguese | Português (Brasil) |
| `ru` | Русский | Русский |
| `sk` | Slovak | Slovenčina |
| `vi` | Vietnamese | Tiếng Việt |
### View options
* Default view
![Default card][header-default-card]
![Default no header][no-header-default-card]
* Calendar card
![Calendar card][header-calendar-card]
![Calendar no header][no-header-calendar]
* Horizon graph
![Dynamic card no header][no-header-dynamic-graph]
![Horizon card][header-horizon-graph]
![Horizon card no header][no-header-horizon-graph]
* Compact view
![Compact card][header-compact-card]
![Compact card no header][no-header-compact-card]
* Compact mode minimal
![Compact minimal][compact-mode-minimal]
## Installation
### [HACS](https://hacs.xyz) (Home Assistant Community Store)
Use this link to directly go to the repository in HACS
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=ngocjohn&repository=lunar-phase-card&category=plugin)
or
1. If HACS is not installed yet, download it following the instructions on [https://hacs.xyz/docs/use/#getting-started-with-hacs](https://hacs.xyz/docs/use/#getting-started-with-hacs)
2. Open HACS in Home Assistant
3. Search for `Lunar Phase Card`
4. Click the download button. ⬇️
5. Force refresh the Home Assistant page `Ctrl` + `F5` / `Shift` + `⌘` + `R`
6. Add `lunar-phase-card` to your dashboard
### Manual
Click to expand installation instructions
1. Download the [lunar-phase-card.js](https://github.com/ngocjohn/lunar-phase-card/releases/latest).
2. Place the downloaded file on your Home Assistant machine in the `config/www` folder (when there is no `www` folder in the folder where your `configuration.yaml` file is, create it and place the file there).
3. In Home Assistant go to `Configuration->Lovelace Dashboards->Resources` (When there is no `resources` tag on the `Lovelace Dashboard` page, enable advanced mode in your account settings, and retry this step).
4. Add a new resource:
- Url = `/local/lunar-phase-card.js`
- Resource type = `module`
5. Force refresh the Home Assistant page `Ctrl` + `F5` / `Shift` + `⌘` + `R`.
6. Add lunar-phase-card to your page.
## Configuration
All options can be configured in the GUI editor. To configure the Lunar Phase Card, you can use the following parameters in your Lovelace configuration:
![Card config editor][card-config-editor]
| Name | Type | Requirement | Description |
| ------------------- | ------- | ----------- | --------------------------------------------------------------------- |
| `type` | string | Required | The type of the card. For this card, use `custom:lunar-phase-card`. |
| `entity` | string | Optional | The entity_id from Lunar Phase custom component `sensor.*_moon_phase` |
| `use_default` | boolean | Optional | Whether to use default settings. Defaults to `true`. |
| `use_entity` | boolean | Optional | Whether to use entity settings. Defaults to `false`. |
| `use_custom` | boolean | Optional | Whether to use custom settings. Defaults to `false`. |
| `show_background` | boolean | Optional | Whether to show the background image. Defaults to `false`. |
| `compact_view` | boolean | Optional | Whether to display the card in a compact view. Defaults to `false`. |
| `compact_mode` | string | Optional | Mode for compact view. Options: `default`, `minimal`. |
| `12hr_format` | boolean | Optional | Whether to display time in 12-hour format. Defaults to `false`. |
| `mile_unit` | boolean | Optional | Whether to display distance in miles. Defaults to `false`. |
| `hide_buttons` | boolean | Optional | Whether to hide the buttons in header. Defaults to `false`. |
| `calendar_modal` | boolean | Optional | Whether to use calendar as modal popup. Defaults to `false`. |
| `default_card` | string | Optional | Default view of the card. Options: `base`, `calendar`, `horizon`. Defaults to `base`. |
| `moon_position` | string | Optional | Position of the moon image. Options: `left`, `right`. Defaults to `left`. |
| `southern_hemisphere` | boolean | Optional | Adjusts the moon orientation for southern hemisphere users. Defaults to `false`. |
| `number_decimals` | number | Optional | Number of decimals for numerical values. Defaults to `2`. |
| `selected_language` | string | Optional | ISO code of the language to be used. Defaults to system or `en`. |
| `latitude` | number | Optional | The latitude for which to calculate the lunar phase. |
| `longitude` | number | Optional | The longitude for which to calculate the lunar phase. |
| `hide_items` | list | Optional | List of items to hide in data view |
| `theme` | object | Optional | Apply theme on card. |
| `font_customize` | object | Optional | Customize fonts for the card. See below for details. |
| `graph_config` | object | Optional | Configuration for the chart. See below for details. |
> [!NOTE]
> The `entity` parameter is not required. It refers to the entity ID from the Lunar Card Custom component, which can be installed [here](https://github.com/ngocjohn/lunar-phase). If the `entity` is not defined, the card will use the default latitude and longitude from the system configuration.
### Font Customization Options
| Name | Type | Description |
| --------------------- | ------- | ------------------------------------------------------------------------- |
| `header_font_size` | string | Font size for the header. Options: `auto`, `small`, `medium`, `large`, `x-large`, `xx-large`. Defaults to `x-large`. |
| `header_font_style` | string | Text style for the header. Options: `none`, `capitalize`, `uppercase`, `lowercase`. Defaults to `capitalize`. |
| `header_font_color` | string | Color for the header text. |
| `label_font_size` | string | Font size for labels. Options: `auto`, `small`, `medium`, `large`, `x-large`, `xx-large`. Defaults to `auto`. |
| `label_font_style` | string | Text style for labels. Options: `none`, `capitalize`, `uppercase`, `lowercase`. Defaults to `none`. |
| `label_font_color` | string | Color for label text. |
| `hide_label` | boolean | Whether to hide labels on the card. Defaults to `false`. |
### Chart Configuration Options
| Name | Type | Description |
| --------------------- | ------- | ------------------------------------------------------------------------- |
| `graph_type` | string | Type of the graph. Options: `default`, `dynamic`. Defaults to `default`. |
| `y_ticks` | boolean | Whether to show y-axis ticks. Defaults to `false`. |
| `x_ticks` | boolean | Whether to show x-axis ticks. Defaults to `false`. |
| `show_time` | boolean | Whether to show time labels on the chart. Defaults to `true`. |
| `show_current` | boolean | Whether to show the current moon position. Defaults to `true`. |
| `show_highest` | boolean | Whether to show the highest moon point. Defaults to `true`. |
| `y_ticks_position` | string | Position of the y-axis ticks. Options: `left`, `right`. Defaults to `left`.|
| `y_ticks_step_size` | number | Step size for y-axis ticks. Defaults to `30`. |
| `time_step_size` | number | Step size for time labels. Defaults to `30`. |
### Example Configuration
Here's an example configuration for the Lunar Phase Card:
```yaml
type: custom:lunar-phase-card
entity: ""
use_default: true
use_custom: false
use_entity: false
show_background: true
selected_language: en
compact_view: false
12hr_format: false
mile_unit: false
hide_buttons: false
calendar_modal: false
default_card: base
moon_position: left
southern_hemisphere: false
number_decimals: 2
graph_config:
y_ticks: false
x_ticks: false
show_time: true
show_current: true
show_highest: true
y_ticks_position: left
y_ticks_step_size: 30
time_step_size: 30
graph_type: default
font_customize:
header_font_size: x-large
header_font_style: capitalize
header_font_color: ""
label_font_size: auto
label_font_style: none
label_font_color: ""
hide_label: false
latitude: 50.0874654
longitude: 14.4212535
```
## Contribution Guidelines
We welcome contributions and are grateful for your support in improving this project. If you'd like to contribute, please follow our [Contribution Guidelines](docs/CONTRIBUTING.md) to get started.
## Support
If you like the card, consider supporting the developer
---
© 2024 Viet Ngoc
[https://github.com/ngocjohn/](https://github.com/ngocjohn/)
[header-default-card]: https://raw.githubusercontent.com/ngocjohn/lunar-phase-card/main/assets/lunar-default-view.gif
[no-header-default-card]: https://raw.githubusercontent.com/ngocjohn/lunar-phase-card/main/assets/no_header_default.gif
[header-calendar-card]: https://raw.githubusercontent.com/ngocjohn/lunar-phase-card/main/assets/lunar-header-calendar.gif
[no-header-calendar]: https://raw.githubusercontent.com/ngocjohn/lunar-phase-card/main/assets/no_header_calendar.gif
[header-horizon-graph]: https://raw.githubusercontent.com/ngocjohn/lunar-phase-card/main/assets/lunar-header-horizon-graph.gif
[no-header-horizon-graph]: https://raw.githubusercontent.com/ngocjohn/lunar-phase-card/main/assets/no_header_horizon_graph.gif
[no-header-dynamic-graph]: https://raw.githubusercontent.com/ngocjohn/lunar-phase-card/main/assets/no_header_dynamic_graph.gif
[header-compact-card]: https://raw.githubusercontent.com/ngocjohn/lunar-phase-card/main/assets/lunar-compact-view.png
[no-header-compact-card]: https://raw.githubusercontent.com/ngocjohn/lunar-phase-card/main/assets/no_header_compact.png
[card-config-editor]:https://raw.githubusercontent.com/ngocjohn/lunar-phase-card/main/assets/lunar-config-editor.gif
[compact-mode-minimal]: https://raw.githubusercontent.com/ngocjohn/lunar-phase-card/main/assets/lunar-compact-minimal.gif
[hacs-default]: https://img.shields.io/badge/HACS-Default-blue?style=flat&logo=homeassistantcommunitystore&logoSize=auto
[hacs-default-link]: https://my.home-assistant.io/redirect/hacs_repository/?owner=ngocjohn&repository=lunar-phase-card&category=plugin
[hacs-validate]: https://github.com/ngocjohn/lunar-phase-card/actions/workflows/validate.yaml/badge.svg
[hacs-validate-link]: https://github.com/ngocjohn/lunar-phase-card/actions/workflows/validate.yaml
[total-downloads]: https://img.shields.io/github/downloads/ngocjohn/lunar-phase-card/total?style=flat&logo=homeassistantcommunitystore&logoSize=auto&label=Downloads&color=%2318BCF2
[latest-downloads]:https://img.shields.io/github/downloads/ngocjohn/lunar-phase-card/latest/total?style=flat&logo=homeassistantcommunitystore&logoSize=auto
[bmac-link]: https://www.buymeacoffee.com/ngocjohn
[bmac-badge]: https://img.shields.io/badge/_-buy_me_a_coffee-F28834?style=flat&logo=buymeacoffee&labelColor=grey&color=%23F28834
[forum-url]: https://community.home-assistant.io/t/lunar-phase-integration-for-home-assistant
[forum-badge]: https://img.shields.io/badge/forum-community?style=flat&logo=homeassistant&label=community&color=blue