CountdownTimer

A real‑time countdown timer that shows the time remaining until a specified target date/time. It updates every second, offers customizable formatting, and displays a completion message when the countdown reaches zero. Suitable for any site.

Use Cases

• Event countdowns (product launches, webinars, conferences, grand openings)
• Sales deadlines (limited‑time offers, flash sales, promotional periods)
• Project milestones (delivery dates, release deadlines, sprint endings)
• Course enrollment deadlines (registration windows, early‑bird pricing)
• Booking cutoffs (reservation deadlines, ticket sales closing)
• Special occasions (holidays, anniversaries, celebrations)
• Auction endings (bid deadlines, marketplace listings)
• Content releases (new features, product drops, content launches)

Properties

targetDate

ISO 8601 formatted date/time string representing the countdown target. Timer displays time remaining until this moment. Type: string.

Tip: Use UTC (Z suffix) for consistent behavior across time zones; include the time component for exact deadlines; ensure the date is in the future—past dates will immediately show the completion message.

title

Optional heading displayed above the countdown. Use to provide context about what the timer represents. Type: string.

Visual Impact: Displays as an h2 heading above the countdown with theme‑aware styling.

Tip: Keep under 50 characters for readability; frame as what’s ending/starting to create urgency; explain WHAT is being counted down to.

showLabels

Whether to show time unit labels (DAYS, HOURS, MINUTES, SECONDS) below each number. Type: boolean. Default: true.

Visual Impact: true – Shows uppercase labels below numbers for clarity; false – Shows only numbers (more minimalist).

Tip: Use true for general audiences who benefit from explicit labels; use false for a clean, minimal aesthetic where context is obvious.

fontSize

Size preset for countdown numbers and labels. Type: string. Options: small, medium, large. Default: medium.

Visual Impact: small – Numbers: 24px, Labels: 10px (suitable for sidebars, cards, compact spaces); medium – Numbers: 48px, Labels: 12px (default size, works well in most contexts); large – Numbers: 72px, Labels: 14px (hero sections, landing pages, prominent placements).

Tip: Use ‘large’ for hero sections; ‘medium’ for content cards; ‘small’ for sidebars.

onCompleteMessage

Message displayed when countdown reaches zero. Use to prompt action or inform users about next steps. Type: string. Default: Event Started!.

Visual Impact: Replaces countdown numbers with this message in the same fontSize.

Tip: Include a call‑to‑action if appropriate; clearly state what happened; frame positively when possible.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Applies to the outermost Section container. Type: string.

Tip: Parsed by cssParser utility. Tenants only affect their own pages (multi‑tenant isolation enforced).

Best Practices

• Use ISO 8601 date format for targetDate (e.g., '2025-12-31T23:59:59Z')
• Set showLabels=true for clarity (helps users understand time units)
• Choose appropriate fontSize based on page context (large for hero sections, medium for cards, small for sidebars)
• Provide meaningful completion messages that prompt action (e.g., 'Event Started! Join Now')
• Use title to provide context about what the countdown represents
• Place prominently on landing pages and promotional sections for maximum impact

Common Mistakes

Using past dates for targetDate causing immediate completion

Why it's a problem: Countdown immediately shows completion message if target date is in the past.

Fix: Ensure targetDate is in the future. Validate date before generating page.

Forgetting time component in targetDate (e.g., '2025-12-31' instead of '2025-12-31T23:59:59Z')

Why it's a problem: Without time component, defaults to midnight which may not be intended deadline.

Fix: Always include full ISO 8601 timestamp: '2025-12-31T23:59:59Z'

Using local time instead of UTC causing timezone confusion

Why it's a problem: Users in different timezones see different countdown values.

Fix: Use UTC timezone (Z suffix) for consistent behavior: '2025-12-31T23:59:59Z'

Setting fontSize too large for mobile viewport

Why it's a problem: Large countdown numbers may overflow on mobile devices.

Fix: Use fontSize='medium' for general use. Reserve 'large' for desktop‑focused hero sections with responsive design.

Using generic completion message ('Done!') that doesn’t prompt action

Why it's a problem: Missed opportunity to guide users on what to do next.

Fix: Use actionable completion messages: 'Event Started! Join Now' or 'Sale Ended - Check Back Next Month'