NWS Alert Card for Home Assistant

A custom Lovelace card that displays active US National Weather Service alerts with real-time updates, severity-based color coding, and expandable descriptions.

Disclaimer‼️

Important: Do not rely on this card for critical weather information. Always consult the National Weather Service or other competent weather providers for important safety decisions.

Features

• Real-time NWS weather alerts for your specified zone
• Dynamic location support for mobile devices with automatic zone resolution
• Action triggers to fire activities from within the card
• Alert entity integration for automations and other HA activities outside of the card
• Separate desktop and mobile location configurations
• Severity-based color coding (Extreme, Severe, Moderate, Minor, Unknown)
• Expandable alert descriptions with "Show more/less" toggle
• 24-hour coordinate-to-zone caching to minimize API calls

Installation

HACS

Finding Your NWS Zone

To configure the card, you need your latitude and longitude or a NWS zone ID. There are two ways to find your zone ID:

Method 1: NWS Public Zone Page

1. Visit NWS Public Zones
2. Select your state
3. Find your county/area
4. Note the zone code (format: SSZNNN or SSCNNN)

Method 2: Using Coordinates

1. Get your lat/long coordinates
2. Visit: https://api.weather.gov/points/LAT,LONG (replace LAT,LONG with your coordinates)
3. Find the forecastZone field in the JSON response
4. The zone ID is the last part of the URL (e.g., COZ097)

Zone Format:

• SS = 2-letter state abbreviation (e.g., AK, NY)
• Z or C = Zone or County
• NNN = 3-digit number (e.g., 001, 329)

Examples:

• Fairbanks, Alaska: AKZ844
• Las Vegas, Nevada: NVZ020
• Denver, Colorado: COZ097

Configuration

Basic Configuration (Static Zone)

Add the card to your Lovelace dashboard:

type: custom:nws-alert-card
nws_zone: AKZ844  # Your NWS zone (REQUIRED if not using lat/lon)
email: your-email@example.com  # REQUIRED for NWS API compliance

Configuration Options

Option	Type	Required	Default	Description
email	string	Yes	-	Your email for NWS API User-Agent header
latitude	number or string	Conditional	-	Latitude coordinate (number) or entity ID (string). Required with longitude if nws_zone not specified.
longitude	number or string	Conditional	-	Longitude coordinate (number) or entity ID (string). Required with latitude if nws_zone not specified.
nws_zone	string	Conditional	-	Your NWS zone ID (e.g., WAZ558). Required if lat/lon not specified.
alert_entity	string	No	-	Entity ID of input_text helper for alert data (e.g., input_text.nws_alert_types)
alert_title_font_size	number	No	16	Alert event name font size in pixels (8-48)
alert_trigger_cooldown	number	No	60	Minutes to wait before re-triggering same severity action
description_color	string	No	primary text	CSS color for alert description text (e.g., #333, gray)
description_font_size	number	No	14	Alert description font size in pixels (8-48)
extreme_action	string	No	-	Entity ID of script/automation for Extreme severity
meta_color	string	No	secondary text	CSS color for severity/urgency/certainty text
meta_font_size	number	No	14	Alert metadata (time range, severity/urgency) font size in pixels (8-48)
minor_action	string	No	-	Entity ID of script/automation for Minor severity
mobile_latitude	number or string	No	-	Mobile override for latitude. Must be used with mobile_longitude.
mobile_longitude	number or string	No	-	Mobile override for longitude. Must be used with mobile_latitude.
moderate_action	string	No	-	Entity ID of script/automation for Moderate severity
severe_action	string	No	-	Entity ID of script/automation for Severe severity
show_expanded	boolean	No	false	Show alert descriptions expanded by default
show_severity_markers	boolean	No	true	Show markers for severe alerts
times_color	string	No	secondary text	CSS color for alert time range text
title_color	string	No	inherit	CSS color for the card title
title_font_size	number	No	20	Card title font size in pixels (8-48)
title	string	No	NWS Weather Alert	Card title
update_interval	number	No	300	Seconds between alert checks
zone_color	string	No	secondary text	CSS color for the zone subtitle

Action Triggers

⛔️ WARNING: DO NOT RELY ON THIS CARD FOR CRITICAL ALERTS ⛔️

Always consult the US National Weather Service for official, up to date weather information. The NOAA Weather Radio page is a good source of information. NOAA also has information on weather radios.

Configure scripts or automations to run when alerts appear or severity increases.

Trigger Behavior:

• Actions trigger when NEW alerts appear OR when severity INCREASES
• Only the HIGHEST severity action triggers (not all severities)
• No action when alerts are removed or severity decreases
• Entity IDs must be script.* or automation.* format
• Cooldown Protection: After triggering, each severity has a cooldown period (default 60 minutes)
  • Prevents actions from firing on every page reload
  • Cooldown tracked per severity level in browser localStorage
  • Set alert_trigger_cooldown: 0 to disable cooldown

Example:

type: custom:nws-alert-card
nws_zone: AKZ844
email: user@example.com
moderate_action: script.turn_light_yellow
severe_action: automation.close_curtains
extreme_action: script.play_alarm_sounds
alert_trigger_cooldown: 60  # Minutes between triggers (default: 60)

In this example:

• If a Moderate alert appears: script.turn_light_yellow runs
• If alert upgrades to Severe: automation.close_curtains runs
• If alert upgrades to Extreme: script.play_alarm_sounds runs
• Only the highest severity action triggers each time
• Each action won't trigger again for 60 minutes (even if you reload the page)

Alert Entity Integration

Store active alert data in a Home Assistant entity for use in automations and conditional cards. Alerts are sorted by official NWS priority order (Tsunami Warning highest, Blue Alert lowest).

ℹ️ See Alerts.md for setup instructions and examples.

Dynamic Location Support

The card supports automatic geolocation for mobile devices, allowing different zones for desktop and mobile:

Static Location with Mobile Tracking

type: custom:nws-alert-card
latitude: 46.6062  # Home location (desktop)
longitude: -122.3321
mobile_latitude: device_tracker.my_phone  # Track phone location on mobile
mobile_longitude: device_tracker.my_phone
email: your-email@example.com

Mixed Configuration

Use static zone on desktop, track device on mobile:

type: custom:nws-alert-card
nws_zone: COZ097  # Desktop fallback
mobile_latitude: device_tracker.my_phone  # Mobile overrides
mobile_longitude: device_tracker.my_phone
email: your-email@example.com

How It Works

• Coordinates are automatically converted to NWS zones using the NWS Points API
• Mobile detection uses Home Assistant Companion app detection, mobile user agents, and screen width
• Zone lookups are cached for 24 hours to minimize API calls
• Entity locations update dynamically (5-second debounce to prevent excessive API calls)

On mobile devices:

• Uses mobile_latitude/mobile_longitude if configured
• Falls back to latitude/longitude if mobile coords not set
• Falls back to nws_zone if coordinates fail to resolve

On desktop:

• Uses latitude/longitude if configured
• Falls back to nws_zone if lat/lon not set or fail to resolve

Configuration Precedence

When multiple location options are configured:

1. Mobile lat/lon - Used on mobile if mobile_latitude and mobile_longitude are set
2. Base lat/lon - Used if latitude and longitude are set
3. Static zone - Used if lat/lon not set or fail to resolve (nws_zone)

This allows nws_zone to act as a fallback without overriding coordinate-based configuration.

Severity Color Coding

Alerts are color-coded by severity on the left border:

• Extreme (Red): Life-threatening situations
• Severe (Orange): Significant threat to life/property
• Moderate (Yellow): Possible threat to life/property
• Minor (Green): Minimal threat to life/property
• Unknown (Gray): Severity not specified

API Information

This card uses the National Weather Service API:

• Endpoint: https://api.weather.gov/alerts/active/zone/{zone}
• Format: GeoJSON
• Rate limiting: Implemented with exponential backoff
• Timeout: 10 seconds per request

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - see LICENSE file for details

Credits

Created by sxdjt

Uses data from the National Weather Service API