A MagicMirror² module for displaying animated countdown timers with celebration effects when your events arrive!

• Features
• Screenshots
• Installation
• Update
• Configuration
• Configuration Options
  • Global Options
  • Event Object Properties
  • Recurring Event Properties
  • Counter Styles
• How It Works
• Customization
  • Recurring Countdowns
  • Responsive Scaling
  • Custom Celebration Emojis
  • Disabling Arrival Effects
  • Hiding the Icon
• Troubleshooting
• Contributing
• License

• Four Counter Styles - Flip clock, progress rings, animated hourglass & digital clock
• Recurring Countdowns - Weekly, monthly, or yearly countdowns that automatically reset
• Optional Celebration Animation - Customizable falling emoji particles when your event arrives
• Optional Arrival Glow Effect - Counter boxes pulse with a glowing effect when countdown reaches zero
• Optional Bouncing Icon - Add a bouncing emoji above your event name, or hide it for a minimal look
• Responsive Scaling - Automatically scales to fit any MagicMirror region width
• Column Alignment - Multiple countdown modules in the same column automatically align their centers
• Grayscale Mode - Inverted grayscale option for classic MagicMirror aesthetic

All four counter styles showing custom colors, grayscale mode, celebration effects, and a recurring countdown.

1. Navigate to your MagicMirror modules folder:

cd ~/MagicMirror/modules

2. Clone this repository:

git clone https://github.com/ElliAndDad/MMM-AnimatedCountdowns.git

3. Install emoji font (required for icons and celebration emojis):

sudo apt install fonts-noto-color-emoji

To update the module to the latest version:

cd ~/MagicMirror/modules/MMM-AnimatedCountdowns
git pull

Then restart MagicMirror to apply changes.

Add the module to your config/config.js file. Copy the config below and customize it to your needs:

{
    module: "MMM-AnimatedCountdowns",
    position: "top_left",
    config: {
        // Global settings
        colorMode: true,                                // false = grayscale (inverted for MagicMirror)
        showPassedEventsForHours: 24,                   // Hours to show event after it passes

        // Add your events here
        events: [
            {
                name: "Christmas!",                     // Event display name (required)
                date: "2026-12-25",                     // Target date YYYY-MM-DD (required)
                time: null,                             // Target time HH:MM or HH:MM:SS
                icon: "🎄",                             // Emoji icon (null to hide)
                counterStyle: "flip",                   // "digital", "rings", "flip", or "hourglass"
                textColor: "#ff0000",                   // Event name color
                accentColor: "#00ff00",                 // Ring/glow accent color
                counterTextColor: "#ffffff",            // Counter numbers color
                celebrateOnDay: true,                   // Show celebration animation
                celebrationEmojis: ["🎄", "🎅", "⭐"]   // Custom emojis for this event
            },
            {
                name: "New Year!",
                date: "2027-01-01",
                time: "00:00",
                icon: "🥂",
                counterStyle: "flip",
                textColor: "#ffd700",
                accentColor: "#ffd700"
            }
        ]
    }
},

One-time events:

1. Before the event: Shows a countdown with your chosen counter style
2. When event arrives: Countdown shows all zeros with a pulsing glow effect, celebration animation begins with falling emojis
3. After 24 hours: Event automatically hides (configurable with showPassedEventsForHours)

Recurring events:

1. Before the event: Shows a countdown (respects showFromDay or showDaysBefore if set)
2. When event arrives: Celebration plays for the configured duration
3. After celebration: Countdown automatically resets to the next occurrence
4. Between occurrences: Hides if outside the show period, otherwise counts down to the next occurrence

Create countdowns that automatically reset after each occurrence:

Weekly countdown (e.g., countdown to the weekend):

{
    name: "Weekend!",
    icon: "🎉",
    recurrence: "weekly",
    targetDay: 5,           // 0=Sun, 1=Mon, 2=Tue, 3=Wed, 4=Thu, 5=Fri, 6=Sat
    time: "17:00",          // Friday at 5pm
    showFromDay: 1          // Only show Monday through Friday
}

Monthly countdown (e.g., countdown to payday):

{
    name: "Payday!",
    icon: "💰",
    recurrence: "monthly",
    targetDay: 15,          // 15th of each month
    time: "09:00",
    showDaysBefore: 7       // Only show 7 days before
}

Yearly countdown (e.g., recurring birthday):

{
    name: "Mom's Birthday!",
    icon: "🎂",
    recurrence: "yearly",
    targetMonth: 3,         // March
    targetDay: 15,
    showDaysBefore: 14      // Show starting 2 weeks before
}

When a recurring countdown reaches zero, the celebration plays for the configured showPassedEventsForHours, then the countdown resets to the next occurrence. If showFromDay or showDaysBefore is set, the countdown hides until the next show period begins.

All event styling options (celebrateOnDay, celebrationEmojis, counterStyle, colors, etc.) work with recurring events just like one-time events.

The module automatically scales to fit the width of your MagicMirror region. Place it in a narrow column and it stays compact; place it in a wider region and everything scales up proportionally — icons, text, counters, and spacing all adjust automatically.

Column Alignment: When you have multiple countdown module instances in the same column (e.g., one in top_left and another in bottom_left), they automatically match the width of the widest non-countdown module in that column. This ensures all countdown modules in a column are centered and aligned with each other, regardless of their counter style or content width.

You can customize the falling emojis for each event:

{
    name: "Halloween Party",
    date: "2026-10-31",
    icon: "🎃",
    textColor: "#ff6600",
    accentColor: "#ff6600",
    celebrationEmojis: ["🎃", "👻", "🦇", "🕷️", "💀"]
}

The celebration particles and arrival glow can be controlled separately:

Disable celebration particles only (glow still shows briefly):

{
    name: "Quiet Event",
    date: "2026-08-01",
    celebrateOnDay: false
}

Disable both celebration and glow by hiding the event immediately when it arrives:

{
    module: "MMM-AnimatedCountdowns",
    position: "top_left",
    config: {
        showPassedEventsForHours: 0,  // Event disappears immediately
        events: [...]
    }
}

If you prefer a cleaner look without the bouncing emoji icon:

{
    name: "Minimal Event",
    date: "2026-05-01",
    icon: null
}

Make sure you completed installation step 3 (installing the emoji font):

sudo apt install fonts-noto-color-emoji

Then restart MagicMirror.

• Check that the module name in config.js matches exactly: "MMM-AnimatedCountdowns"
• Verify the position is valid (e.g., "top_left")
• Check the browser console for JavaScript errors

• Verify your date format is correct (YYYY-MM-DD)
• Check that event dates are in the future
• Events automatically hide 24 hours after they pass

• Make sure celebrateOnDay is set to true
• Check that the event date/time has actually passed

• The glow uses the accentColor property - make sure it's set to a visible color
• The glow only appears when the countdown reaches zero

• Make sure recurrence is set to "weekly", "monthly", or "yearly"
• Check that targetDay is set correctly (0-6 for weekly, 1-31 for monthly/yearly)
• For yearly events, verify targetMonth is set (1-12)
• If using showFromDay or showDaysBefore, the event may be hidden until the show period begins

• This module uses CSS Container Queries which require a modern browser.
• Make sure your MagicMirror is running on Electron 105+ or a current Chromium-based browser.

1. Fork and clone the repository
2. Install dev dependencies:

   npm install

3. Make your changes
4. Run the linter before committing:

   npm run lint:fix

5. Submit a pull request

MIT License - see LICENSE file for details.