Countdown Boxed
Loading playground
Overview
CountdownBoxed is the promotional face of the countdown family. It counts down to an endDate and renders each unit as boxed digit tiles under a label, separated by colons — the treatment used on promotion banners and offer popups.
It shows days, hours, and minutes only. Seconds are deliberately absent: a ticking seconds digit pulls attention away from the offer on a promotional surface. Reach for Countdown when you need the full breakdown down to the second.
Values are zero-padded to at least two digits, so the layout does not jump as numbers shrink. Unit labels come from Intl and are localized and plural-aware.
Key Business & UX Benefits
- Turns a deadline into a visual centrepiece rather than a line of text, which is what a promotional banner needs to earn its space.
- Four painted styles match the countdown treatments in Figma, so campaign surfaces stay on-brand without bespoke CSS.
- Fixed-width zero-padded digits keep surrounding layout stable as the clock runs down.
- Shares its clock with every other countdown on the page, so a promo banner adds no extra timer cost.
Usage
<LCountdownBoxed :end-date="saleEndsAt" variant="bright" @expired="endSale" />
Variants
variant selects the painted colour style.
| Variant | Use for |
|---|---|
default | The standard treatment on a neutral surface. |
pale | Muted styling where the countdown supports rather than leads. |
bright | High-contrast styling for a campaign hero. |
solid | Filled tiles for maximum emphasis on a busy background. |
Behavior
The component emits expired when the deadline passes — once, on the client only. It does not hide itself, so decide what should happen: refetch the offer, swap in an "offer ended" message, or remove the banner.
Both the clock and the arithmetic come from useCountdown, so everything documented there applies: one shared ticker per page, SSR-stable rendering with no hydration mismatch, and a malformed endDate treated as already expired.
The now prop pins the clock to a fixed instant for tests and Storybook snapshots. Leave it unset in production.
CountdownBoxed stops at minutes, so it reads as stale in the final hour of a sale. For a genuine last-hour push, switch to Countdown where the seconds keep moving.When to Use
- Use
CountdownBoxedon promotional surfaces — banners, offer popups, campaign heroes — where the deadline is part of the visual pitch. - Use
Countdownin running copy, product tiles, or anywhere the remaining time is information rather than decoration.
When NOT to Use
- Do not use it for deadlines inside the final hour, where a minutes-only display looks frozen. Use
Countdowninstead. - Do not use it for elapsed time or progress. It only counts down to a fixed instant and has no start date.
Feature List
- Counts down to an `endDate` (Date or ISO string); no start date
- Renders days, hours, and minutes as individual digit tiles, zero-padded to two digits
- Four painted styles: default, pale, bright, and solid
- Localized, plural-aware unit labels from Intl
- Emits `expired` once, client-side, when the deadline passes
- `role="timer"` with `aria-live="polite"` so assistive technology announces updates
- Shares the page-wide one-second ticker via `useCountdown`; SSR-stable
API Reference
CountdownBoxed
| Prop | Default | Type |
|---|---|---|
endDaterequired | string | DateThe instant the countdown runs toward. There is no start date — it always counts down to this. | |
now | string | DateFreeze the clock at a fixed instant — tests / Storybook only. Production ticks live. | |
variant | default | CountdownBoxedVariant ("default" | "bright" | "pale" | "solid")Painted color style, matching the Figma countdown styles. |
| Event | Type |
|---|---|
expired | (event: "expired"): void |
Related
- Countdown: the text-style countdown, including seconds, and the
useCountdowncomposable. - PopUp Promotion: renders this component when
countdownEndDateis set.