Parameter Based Countdown Timer

A clean, customizable countdown timer that can be configured entirely through URL parameters. Perfect for presentations, OBS overlays, streams, or any scenario where you need a visual countdown.

Inspired by the vdo.ninja use of parameters to configure browser overlays in OBS as opposed to plugins.

Demo

Try it live at: wyomingjarbo.com/countdown

Usage

Simply open index.html in a browser, or use URL parameters to customize the timer: https://wyomingjarbo.com/countdown/index.html?minutes=10&theme=dark

Made to run locally for OBS browser sources.

URL Parameters

Time Configuration

Parameter	Description	Example
date	Set a specific target date/time	?date=2023-12-31 or ?date=2023-12-31T23:59:59
days	Add days to current time	?days=7
hours	Add hours to current time	?hours=3
minutes	Add minutes to current time	?minutes=30
seconds	Add seconds to current time	?seconds=45
timezone	Specify timezone for the timer	?timezone=America/New_York

Multiple time units can be combined: ?days=1&hours=12

Display Options

Parameter	Description	Values
theme	Set the color theme	light (default), dark
display	Set the display format	standard (default), compact
units	Control time unit display	auto (default, hide zero units), full (show all units from highest configured unit down to seconds)
progress	Show progress bar	true, false (default)
title	Add a title above the timer	?title=Meeting%20Timer
endmessage	Custom text or emoji shown when timer completes	?endmessage=🎉 (default: ⌛️)
showonend	Control what to display when timer ends	message (default, shows endmessage), zero (shows 00:00), none (shows nothing)
resume	Resume interrupted timer	true, false (default)
mobile	Control mobile optimization	true (default), false
redirecturl	URL to redirect to when timer completes	?redirecturl=https://example.com
redirectdelay	Seconds to wait before redirecting (default: 1)	?redirectdelay=5
direction	Set timer direction	down (default), up
showcontext	Show original date/time context below SINCE (date-based direction=up only)	true, false (default)

Units

When using units=full, the timer will show all time units from the highest configured unit down to seconds, regardless of whether some values are zero. For example:

• If you set minutes=5, it will show minutes and seconds (05:00)
• If you set hours=1, it will show hours, minutes, and seconds (01:00:00)
• If you set days=1, it will show days, hours, minutes, and seconds (01:00:00:00)

The auto setting (default) intelligently hides units that are zero to keep the display clean. For times larger than 1.5 days (36 hours) it will only show the days unit.

Direction

The direction parameter controls whether the timer counts down or up. When set to direction=up, the timer will begin counting up only after the countdown reaches zero (for relative timers). If the initial duration is set to zero (e.g., ?minutes=0), direction=up starts immediately. For date-based timers, begins after the target date/time is reached. This allows you to show elapsed time since an event or deadline.

&showcontext: When showcontext=true is set (with a date-based timer and direction=up), the timer will display the original target date and time below the SINCE label during direction=up mode. This provides clear context for viewers about when the event or deadline occurred. The context is only shown after the timer transitions to direction=up, not during the countdown phase.

Style Customization

All color parameters accept hex color codes without the # symbol.

Parameter	Description	Example
bgcolor	Background color	?bgcolor=f0f0f0
timercolor	Timer background color	?timercolor=ffffff
textcolor	Main text color	?textcolor=333333
labelcolor	Label text color	?labelcolor=666666
progresscolor	Progress bar color	?progresscolor=4caf50
titlecolor	Title text color	?titlecolor=333333
fontscale	Scales all font sizes	?fontscale=1.5

Note: Custom color parameters currently work best with theme=light (default theme). When using theme=dark, the dark theme's predefined colors will take precedence over custom color settings.

Colors can also accept transparency in the form of an eight digit hex color. (ex. bgcolor=00000000 would be a fully transparent background.)

Timezone Support

The timer supports specifying a timezone to ensure consistent countdown behavior regardless of where it's viewed:

• Use IANA timezone names like America/New_York, Europe/London, Asia/Tokyo
• When a timezone is specified, all time calculations use that timezone instead of the viewer's local timezone
• Useful for coordinating events across different regions

Example: ?date=2023-12-31T00:00:00&timezone=America/New_York

Mobile Optimization

The timer automatically optimizes its display for mobile devices:

• Detects mobile devices and adjusts layout for better viewing
• Can be disabled with ?mobile=false if you prefer the desktop layout on all devices
• Improves readability and touch interaction on small screens
• Especially useful for sharing countdown links that might be opened on phones

Timer Resumption (For Duration-Based Timers)

The timer uses localStorage to allow resuming interrupted timers that are created with duration parameters (days, hours, minutes, seconds):

• If you refresh or close the page during an active countdown, a resume banner will appear when you return
• Click "Resume" or use ?resume=true parameter to continue the countdown
• The timer state is saved every 10 seconds
• Progress bar position is correctly restored when resuming
• Resumable timers expire after 24 hours
• Note: Date-based timers (using the date parameter) do not support resumption

Webhook Integration

The timer can call a webhook URL when the countdown completes, useful for integrating with external systems like Bitfocus Companion:

Parameter	Description	Values
webhookurl	URL to call when timer completes	?webhookurl=https://example.com/api/hook
webhookmethod	HTTP method to use for webhook call	GET (default), POST
webhookdelay	Seconds to wait before calling webhook	?webhookdelay=2 (default: 0)

When using POST method, a JSON payload is sent with the event type and timestamp:

{
  "event": "timer_complete",
  "timestamp": "2023-04-15T12:00:00.000Z"
}

Examples

1. 10-minute timer with dark theme and title:
2. Countdown to a specific date with timezone:
3. 3-day countdown showing all units with progress bar:
4. Presentation timer with custom colors:
5. Custom end message when timer completes:
6. Show zeros when timer ends:
7. Show nothing when timer ends:
8. Resume an interrupted timer:
9. Event timer with mobile optimization disabled:
10. Redirect to a URL when timer completes:
11. Redirect with a 3-second delay:
12. Call a webhook when timer completes: ?minutes=5&webhookurl=https://example.com/api/timer-done
13. Call a webhook with POST and delay: ?minutes=1&webhookurl=https://example.com/api/timer-done&webhookmethod=POST&webhookdelay=2
14. Larger font scale for readability: ?minutes=10&fontscale=1.25
15. direction=up timer (relative): ?minutes=10&direction=up (shows direction=up indicators after timer reaches zero)
16. direction=up timer (date-based) with context: ?date=2023-12-31T23:59:59&direction=up&showcontext=true (shows SINCE and original date/time after date is reached)

OBS Integration Tips

For best results when using as an OBS Browser Source:

1. Set width and height to match your desired dimensions (e.g., 800×200)
2. Enable "Shutdown source when not visible" to conserve resources
3. Disable "Refresh browser when scene becomes active" to prevent timer resets
4. Use custom CSS in OBS to make the background transparent if needed:

body, html { background-color: transparent !important; }
.container { background-color: transparent !important; }

For a semi-transparent timer display:

body, html { background-color: transparent !important; }
.container { background-color: transparent !important; }
#timer, #compact-timer { background-color: rgba(0, 0, 0, 0.5) !important; }

For better readability on varied backgrounds, add text shadow:

.label, #timer-title { text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5) !important; }

Configuration Wizard

For users who prefer a visual way to configure the timer, a user-friendly configuration wizard is available:

1. Navigate to the Countdown Timer Wizard
2. Configure your timer using the intuitive interface:
   • Set time duration or target date/time
   • Choose display options (theme, format, colors)
   • Configure advanced features (redirects, webhooks)
3. The wizard generates your custom URL in real-time
4. Use the "Copy URL" button to copy the configuration to your clipboard
5. Click "Test Timer" to preview your configuration in a new window

This wizard makes it easy for non-technical users to create customized countdown timers without needing to understand URL parameters.

Technical Details

• Pure HTML, CSS, and JavaScript - no dependencies
• Responsive design with font clamps for consistent display at any size
• Optimized for OBS, shared displays, and mobile devices
• Uses the Intl.DateTimeFormat API for timezone support
• Uses localStorage for timer state persistence (resume feature for duration-based timers)
• Font scaling that works well across all device sizes

MIT License