Countdown Timer
Live countdown to a target date/time with days, hours, minutes, and seconds segments.
<arc-countdown-timer>Overview
CountdownTimer renders a live countdown to a target date or time. The display is split into four card-like segments (days, hours, minutes, and seconds), each showing a large mono-spaced number with a gradient accent fill and an uppercase label beneath. Segments are separated by ghost-colored colons.
The component parses any valid ISO 8601 string or JavaScript-parseable date via the target attribute and recalculates the remaining time every second using setInterval. When the countdown reaches zero, an arc-expired event is dispatched and the display switches to a configurable expired message (default: "Expired"). The interval is cleared in disconnectedCallback.
Numbers use font-variant-numeric: tabular-nums so digits keep a constant width as they tick down and the layout does not shift. The segment cards gain a subtle glow on hover via box-shadow: var(--glow-hover), and all transitions respect prefers-reduced-motion. An optional label attribute renders gradient-accent text above the countdown for context like "Launch In" or "Sale Ends".
The hide-zero-segments attribute suppresses leading zero-value segments, which helps when the countdown is under 24 hours and "00 Days" adds nothing.
Guidelines
When to use
- Use for event countdowns, product launches, and sale timers
- Provide a meaningful label like "Launches In" or "Offer Ends"
- Set a custom expired message relevant to the context (e.g. "Now Live!")
- Use hide-zero-segments when the countdown is under 24 hours
- Place inside a Section or Card for visual context
When not to use
- Do not use for elapsed time or stopwatch functionality; this counts down only
- Do not set a target date in the past unless you want the expired state immediately
- Do not place more than one or two countdowns on a single page; they compete for attention
- Do not rely solely on the visual countdown for critical deadlines. Enforce them server-side
- Do not use extremely short countdowns (under 10 seconds) as primary UI; the urgency feels manipulative
Features
- Live countdown updating every second via setInterval
- Interval timer cleared in disconnectedCallback
- Gradient-accent number text with tabular-nums for stable layout
- Card-style segments with hover glow effect
- Fires `arc-expired` custom event when countdown reaches zero
- Configurable expired text via the expired attribute
- Optional label with gradient accent text above the countdown
- hide-zero-segments attribute to suppress leading zero segments
- Respects `prefers-reduced-motion` by disabling transitions
- CSS parts for container, segment, number, label, and separator
Preview
Usage
Countdown Timer is in the marketing domain group, so it is absent from the default @arclux/arc-ui barrel. Import it from@arclux/arc-ui/marketing, or from its own subpath@arclux/arc-ui/countdown-timer. Everything else (the element, the CSS, the framework wrappers, the support it gets) is unchanged.
This component requires JavaScript. No pure HTML/CSS version is available. Use the Web Component directly or a framework wrapper.
<!-- New Year countdown -->
<arc-countdown-timer
target="2026-12-31T00:00:00"
label="New Year"
></arc-countdown-timer>
<!-- Product launch with custom expired text -->
<arc-countdown-timer
target="2026-06-15T09:00:00"
label="Launches In"
expired="Now Live!"
></arc-countdown-timer>
<!-- Short countdown, hiding zero segments -->
<arc-countdown-timer
target="2026-03-01T18:00:00"
hide-zero-segments
></arc-countdown-timer>import { CountdownTimer } from '@arclux/arc-ui-react';
function LaunchBanner({ launchDate }) {
return (
<CountdownTimer
target={launchDate}
label="Launches In"
expired="Now Live!"
onArcExpired={() => console.log('Countdown finished!')}
/>
);
}<script setup>
import { CountdownTimer } from '@arclux/arc-ui-vue';
const launchDate = '2026-12-31T00:00:00';
function handleExpired() {
console.log('Countdown finished!');
}
</script>
<template>
<CountdownTimer
:target="launchDate"
label="New Year"
expired="Happy New Year!"
@arc-expired="handleExpired"
/>
</template><script>
import { CountdownTimer } from '@arclux/arc-ui-svelte';
const target = '2026-12-31T00:00:00';
</script>
<CountdownTimer
{target}
label="New Year"
expired="Happy New Year!"
on:arc-expired={() => console.log('Done!')}
/>import { Component } from '@angular/core';
import { CountdownTimer } from '@arclux/arc-ui-angular';
@Component({
imports: [CountdownTimer],
template: `
<arc-countdown-timer
target="2026-12-31T00:00:00"
label="New Year"
expired="Happy New Year!"
(arc-expired)="onExpired()"
/>
`,
})
export class CountdownComponent {
onExpired() {
console.log('Countdown finished!');
}
}import { CountdownTimer } from '@arclux/arc-ui-solid';
function LaunchCountdown() {
return (
<CountdownTimer
target="2026-12-31T00:00:00"
label="New Year"
expired="Happy New Year!"
/>
);
}import { CountdownTimer } from '@arclux/arc-ui-preact';
function LaunchCountdown() {
return (
<CountdownTimer
target="2026-12-31T00:00:00"
label="New Year"
expired="Happy New Year!"
/>
);
}API
targetstring''- ISO date string or parseable date for the countdown target
labelstring''- Optional label displayed above the countdown
expiredstring'Expired'- Text shown when the countdown reaches zero
hideZeroSegmentsbooleanfalse- Hide leading segments that are zero
Events
arc-expired- Fired when the countdown reaches zero
See Also
- Animated NumberCount-up/down number animation with formatting options.
- StatNumeric statistic display with gradient value and label.
- BadgeCompact pill-shaped label for status indicators, category tags, and notification counts. Seven color variants encode meaning across dashboards, tables, and card layouts.