⏱️ Countdown Component

A versatile countdown timer that displays the time remaining until a target date. Features multiple display formats, configurable units, and smooth animations.

Cards Format

The default format displays each time unit in a separate card with a dark theme. Perfect for hero sections and prominent countdowns.

View Code Example

<script>
  import Countdown from '$lib/components/Countdown.svelte';

  const newYear = new Date('2025-01-01T00:00:00');
</script>

<Countdown targetDate={newYear} format="cards" />

Labels Format

A cleaner, minimal style with large numbers and small labels underneath. Works well on light backgrounds.

View Code Example

<Countdown targetDate={targetDate} format="labels" />

Compact Format

A single-line display like a digital clock. Great for headers or tight spaces.

View Code Example

<Countdown targetDate={targetDate} format="compact" padZeros={true} />

Custom Units

Choose which time units to display. Show only what's relevant to your countdown.

Days Only

Hours & Minutes

Minutes & Seconds

View Code Example

<!-- Days only -->
<Countdown targetDate={date} units={['days']} />

<!-- Hours and minutes -->
<Countdown targetDate={date} units={['hours', 'minutes']} />

<!-- Minutes and seconds -->
<Countdown targetDate={date} units={['minutes', 'seconds']} />

Completion Handling

Customise what happens when the countdown finishes. Show a message, trigger a callback, or hide the countdown entirely.

Tip: Use the onComplete callback to trigger actions when the countdown finishes.

View Code Example

<script>
  function handleComplete() {
    alert('Countdown finished!');
  }
</script>

<Countdown
  targetDate={pastDate}
  completedMessage="🎉 Event started!"
  onComplete={handleComplete}
  hideOnComplete={false}
/>

Custom Separators

In compact format, you can customise the separator between units.

Colon (default)

Dot

Dash

View Code Example

<Countdown targetDate={date} format="compact" separator="." />

Component Features

🎨

Multiple Formats

Choose from cards, labels, or compact display styles to match your design.

⚙️

Flexible Units

Display any combination of days, hours, minutes, and seconds.

✨

Smooth Animations

Subtle animations when digits change, respecting reduced motion preferences.

🎯

Completion Callback

Execute custom logic when the countdown reaches zero.

📦

Zero Dependencies

Pure Svelte and CSS implementation with no external libraries.

♿

Accessible

ARIA live regions and proper labelling for screen reader support.

Quick Start Guide

Copy the Component

Copy Countdown.svelte from src/lib/components/ to your project.

Import and Use

Import the component and set your target date. All other props are optional with sensible defaults.

Customise

Choose your format, units, and add completion handling as needed for your use case.

Props Reference

Prop	Type	Default	Description
`targetDate`	Date \| number \| string	required	Target date/time to count down to
`units`	CountdownUnit[]	['days', 'hours', 'minutes', 'seconds']	Which time units to display
`format`	'compact' \| 'cards' \| 'labels'	'cards'	Display format style
`showLabels`	boolean	true	Show unit labels (Days, Hours, etc.)
`separator`	string	':'	Separator for compact format
`padZeros`	boolean	true	Pad single digits with zeros
`completedMessage`	string	"Time's up!"	Message shown when countdown finishes
`onComplete`	() => void	undefined	Callback when countdown reaches zero
`hideOnComplete`	boolean	false	Hide countdown when complete