⏱️ Countdown Timer

A beautiful, feature-rich countdown timer web application with modern UI, dark/light themes, and persistent state management.

✨ Features

Core Functionality

• ⏱️ Precise Countdown: Set custom date and time for your countdowns
• ⏸️ Pause & Resume: Full control over your timer with pause/resume functionality
• 🔄 Reset: Quickly reset the timer to start fresh
• 💾 Persistent State: Your timer survives page reloads and browser restarts
• 📱 Responsive Design: Works perfectly on desktop, tablet, and mobile devices

Visual & UX

• 🎨 Dark/Light Themes: Toggle between elegant dark and clean light themes
• ⭕ Progress Ring: Visual circular progress indicator
• 🎯 Quick Presets: One-click presets for 1 hour, 1 day, and 7 days
• ✨ Smooth Animations: Polished transitions and hover effects
• ♿ Accessible: ARIA labels, keyboard navigation, and screen reader support

Advanced Features

• 🔔 Browser Notifications: Get notified when your countdown completes (with permission)
• 🔊 Completion Sound: Pleasant audio alert when timer finishes (Web Audio API with fallback)
• 📋 Dynamic Page Title: See remaining time in your browser tab
• ⚡ Performance Optimized: Efficient DOM updates and battery-friendly tick rate
• ✅ Input Validation: Maximum 365-day countdown limit with helpful error messages
• 🔄 Smart State Recovery: Handles expired timers gracefully when page reloads

🚀 Getting Started

Prerequisites

• A modern web browser (Chrome, Firefox, Safari, Edge)
• No build tools or dependencies required!

Installation

1. Clone or download this repository:

   git clone <your-repo-url>
   cd countdown-timer

2. Open the application:

   • Simply open index.html in your web browser
   • Or use a local server:

     # Python 3
     python -m http.server 8000
     
     # Node.js (with npx)
     npx serve

3. Start using:

   • Pick a date and time, or use quick presets
   • Click "Set" to start your countdown
   • Use Pause/Resume/Reset as needed

📖 Usage Guide

Setting a Countdown

1. Manual Entry: Click the date/time input and select your target
2. Quick Presets: Click +1h, +1d, or +7d for instant countdowns
3. Click the Set button to start

Controls

• ⏸️ Pause: Temporarily pause the countdown
• ▶️ Resume: Continue from where you paused
• ↻ Reset: Clear the current countdown

Theme Toggle

• Click the 🌙/☀️ button in the header to switch themes
• Your preference is saved automatically

Browser Notifications

• Grant notification permission when prompted
• Get alerts when your countdown completes
• Works even when the tab is in the background

🏗️ Technical Details

Built With

• Pure HTML5: Semantic markup with accessibility in mind
• Modern CSS3: CSS custom properties, gradients, and animations
• Vanilla JavaScript: No frameworks, just clean ES6+ code

Key Technologies

• LocalStorage API: For persistent state and theme preferences
• Notifications API: Desktop notifications on countdown completion
• SVG Graphics: Scalable progress ring visualization
• CSS Variables: Dynamic theming system

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Opera 76+

📂 Project Structure

countdown-timer/
├── index.html          # Main HTML structure
├── style.css           # All styling and themes
├── countdown.js        # Application logic
└── README.md          # This file

🎨 Customization

Changing Colors

Edit the CSS custom properties in style.css:

:root {
  --accent: #6ee7b7;      /* Primary accent color */
  --accent-2: #60a5fa;    /* Secondary accent color */
  --bg: #0f1724;          /* Background color */
  /* ... */
}

Adjusting Presets

Modify the preset buttons in index.html:

<button type="button" data-add="3600">+1h</button>
<button type="button" data-add="86400">+1d</button>
<button type="button" data-add="604800">+7d</button>

The data-add attribute specifies seconds to add.

Changing Maximum Duration

Edit the constant in countdown.js:

const MAX_COUNTDOWN_DAYS = 365; // Maximum 1 year countdown

🐛 Known Issues

• Some browsers may block notifications by default (requires user permission)
• Theme transitions may flicker on slower devices
• Audio autoplay may be blocked in some browsers (resolved by playing test sound on user interaction)

🔮 Future Enhancements

• Multiple simultaneous timers
• Custom completion sound upload
• Countdown templates/presets
• Export/share countdown links
• Fullscreen mode
• Custom labels for timers
• Sound volume control
• Recurring timers

🔧 Recent Improvements (Latest Update)

Bug Fixes

• Fixed pause/resume timer drift: Corrected the calculation when resuming from pause to prevent time drift
• Fixed expired timer handling: Timer state now properly clears when loading an expired countdown from storage
• Improved audio reliability: Added test sound on user interaction to bypass browser autoplay policies

New Features

• Completion sound effect: Plays a pleasant 3-tone chord (C-E-G major) when countdown completes
• Web Audio API fallback: Generates sounds programmatically if no audio file is provided
• Smart audio priming: Quietly enables audio on first user interaction to ensure completion sound works

Code Quality

• Better error handling for audio playback
• Cleaner state management for pause/resume functionality
• Added comprehensive inline documentation
• Performance optimizations for sound generation

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📄 License

This project is open source and available under the MIT License.

👤 Author

Built during an internship project.

🙏 Acknowledgments

• Google Fonts (Inter typeface)
• Inspiration from various timer applications
• Modern web design principles

---

Enjoy your countdown! ⏱️✨

For questions or support, please open an issue on GitHub.