CountdownTimer

Real-time countdown timer component that displays the time remaining until a target date/time. It updates every second, offers customizable formatting, and shows a completion message when the countdown ends. Suitable for any site type.

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:

• timezone: Use UTC (Z suffix) for consistent behavior across time zones.
• precision: Include time component for exact deadlines, not just date.
• future-dates: Ensure 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 h2 heading above countdown with theme-aware styling.

Tip:

• concise: Keep under 50 characters for readability.
• actionable: Frame as what’s ending/starting to create urgency.
• context: 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:

• clarity: Use true for general audiences who benefit from explicit labels.
• minimal-design: 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:

• hero-sections: Use ‘large’ for maximum impact on landing pages.
• content-cards: Use ‘medium’ for balanced visibility in content areas.
• sidebars: Use ‘small’ for compact spaces and secondary placements.

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:

• actionable: Include call-to-action if appropriate (“Shop Now”, “Join Now”).
• informative: Clearly state what happened (“Sale Ended”, “Event Started”).
• positive: Frame positively when possible (“Now Available!” vs “Deadline Passed”).

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 the 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'.