@lgs1920/countdown

v1.3.1

Published

a month ago

A localized, theme-aware countdown Web Component built with Web Awesome.

0High
0Medium
0Low

`@lgs1920/countdown`

@lgs1920/countdown is a Web Component designed exclusively for applications using Web Awesome. It renders a countdown with optional custom unit labels and Web Awesome digit cards. It requires Web Awesome at runtime for its stylesheet, theme tokens, cards, animations, and error messages. It cannot function correctly outside a Web Awesome environment.

The current release is 1.3.1. See the npm package.

Open the live demo · View the changelog · Visit LGS1920 · View the repository on GitHub

The live demo is based on Build Awesome (formerly Eleventy/11ty), built with Web Awesome, and uses icons from Font Awesome. It shows how the component counts down to a target date and lets you try its card appearances, flip and fade animations, translated labels, themes, color modes, brand colors, and responsive single-row layout.

Inspired by FlipClock.

Breaking change in 1.2

Version 1.2 removes the lang attribute. Set the translated unit labels through the legend property instead:

countdown.legend = {
    days: 'Jours',
    hours: 'Heures',
    minutes: 'Minutes',
    seconds: 'Secondes',
}

Show Video

Set legend to false to hide the unit labels.

The component supports:

ISO 8601 target dates with explicit timezone offsets;
Days from one to three digits, with a hard limit of 999 days;
two-digit Hours, Minutes, and Seconds values;
filled, outlined, filled-outlined, and plain card appearances;
FlipDown-style flip transitions and fade transitions;
automatic fade fallback for outlined and plain cards;
an adjustable height / width ratio using the golden ratio by default;
customizable or optional unit labels through the legend property;
optional hiding of unused Days and Hours units through showAllDigits;
optional hiding of Seconds through noSeconds;
one horizontal row at every viewport size.

Installation

The package requires Node.js 20 or newer, or Bun 1.1 or newer.

Install it with your package manager:

npm install @lgs1920/countdown

bun add @lgs1920/countdown

The package declares Web Awesome as a direct dependency, so it is installed automatically. Import Web Awesome's stylesheet in the host application, then import the countdown package:

import '@awesome.me/webawesome/dist/styles/webawesome.css'
import '@lgs1920/countdown'

The countdown package automatically registers the Web Awesome components it needs and registers <lgs1920-countdown> itself. Keeping the stylesheet import in the host application lets that application control when and how Web Awesome styles are loaded.

Web Awesome dependencies

The countdown uses these Web Awesome components at runtime:

| Component | Used for | | --- | --- | | wa-card | The individual digit cards and their filled, outlined, filled-outlined, and plain appearances. | | wa-animation | The flip and fade transitions applied when a digit changes. | | wa-callout | The error state shown for missing, invalid, or out-of-range target dates. |

The Web Awesome stylesheet provides the --wa-* theme, typography, spacing, border, radius, and color tokens consumed by the component. A host application can override these tokens or the --lgs-countdown-* custom properties documented below.

Use the public package entry point shown above so the three Web Awesome components are registered automatically. If you import the lower-level @lgs1920/countdown/countdown entry point directly, you must load the stylesheet and register the Web Awesome components yourself before using <lgs1920-countdown>:

import '@awesome.me/webawesome/dist/styles/webawesome.css'
import '@awesome.me/webawesome/dist/components/animation/animation.js'
import '@awesome.me/webawesome/dist/components/callout/callout.js'
import '@awesome.me/webawesome/dist/components/card/card.js'
import '@lgs1920/countdown/countdown'

Basic usage

The only required value is an ISO 8601 target date. Include an explicit timezone so the target is unambiguous across browsers and locations.

<lgs1920-countdown
    target-date="2026-12-31T23:59:59+01:00"
></lgs1920-countdown>

The component renders four units in this order:

Days     Hours     Minutes     Seconds

The countdown does not manage languages. Supply the translated unit labels through the legend property:

const countdown = document.querySelector('lgs1920-countdown')
countdown.legend = {
    days: 'Jours',
    hours: 'Heures',
    minutes: 'Minutes',
    seconds: 'Secondes',
}

To display only the digits:

countdown.legend = false

By default, Days and Hours are only displayed when they are part of the initial countdown duration. Once an initial duration includes one of these units, that unit remains visible until the countdown expires. Minutes and Seconds are displayed by default.

Use show-all-digits to keep all four units visible, including zero-valued Days and Hours:

<lgs1920-countdown
    show-all-digits
    target-date="2026-12-31T23:59:59+01:00"
></lgs1920-countdown>

Use no-seconds to display only the relevant day, hour, and minute units:

<lgs1920-countdown
    no-seconds
    target-date="2026-12-31T23:59:59+01:00"
></lgs1920-countdown>

Unit labels expose the public legend CSS part. Customize their size from the host application with ::part(legend):

lgs1920-countdown::part(legend) {
    font-size: 0.75rem;
}

The package registers the custom element once and exports the component class and its date and option helpers:

import {getCountdownState, Lgs1920Countdown} from '@lgs1920/countdown'

Attributes

| Attribute | Values | Default | Description | | --- | --- | --- | --- | | target-date | ISO 8601 date/time | None | Counts down to the target. Missing or invalid values render an error state. | | appearance | filled, outlined, filled-outlined, plain | filled-outlined | Selects the Web Awesome card treatment for every digit. | | animation | flip, fade | flip | Selects the transition used when a digit changes. | | ratio | Any positive finite number | 1.618033988749895 | Sets the card height / width ratio. The default is the golden ratio. | | show-all-digits | Boolean attribute | Not set | Keeps Days and Hours visible even when their values are zero. | | no-seconds | Boolean attribute | Not set | Hides the Seconds unit. |

Properties

| Property | Type | Default | Description | | --- | --- | --- | --- | | legend | Object with days, hours, minutes, and seconds strings, or false | English labels | Sets the visible and accessible label for each countdown unit. Set to false to hide unit labels. | | showAllDigits | Boolean | false | Keeps Days and Hours visible even when their values are zero. | | noSeconds | Boolean | false | Hides the Seconds unit while keeping Minutes visible. |

`target-date` validation

The countdown accepts targets up to 999 days from the current time. Days use one to three cards, with a maximum value of 999. Hours, minutes, and seconds always use two cards and are zero-padded.

A missing target displays an error message.
An invalid date displays an error message.
A target more than 999 days away displays a range error.
An expired target remains visible at 0 days, 00 hours, 00 minutes, and 00 seconds.

<!-- Accepted: days are within the three-card limit -->
<lgs1920-countdown target-date="2026-12-31T23:59:59+01:00"></lgs1920-countdown>

<!-- Invalid: this is not an ISO 8601 date -->
<lgs1920-countdown target-date="not-a-date"></lgs1920-countdown>

`ratio`

The ratio is calculated as height / width. It must be a positive finite number. Invalid values fall back to the golden ratio.

<lgs1920-countdown
    ratio="1.25"
    target-date="2026-12-31T23:59:59+01:00"
></lgs1920-countdown>

Card appearances

The component uses the standard Web Awesome appearance names:

filled: opaque themed fill without a border;
outlined: transparent background with a standard border;
filled-outlined: opaque themed fill with a standard border;
plain: transparent background without a border.

<lgs1920-countdown appearance="filled" target-date="2026-12-31T23:59:59+01:00"></lgs1920-countdown>
<lgs1920-countdown appearance="outlined" target-date="2026-12-31T23:59:59+01:00"></lgs1920-countdown>
<lgs1920-countdown appearance="filled-outlined" target-date="2026-12-31T23:59:59+01:00"></lgs1920-countdown>
<lgs1920-countdown appearance="plain" target-date="2026-12-31T23:59:59+01:00"></lgs1920-countdown>

Digit animations

flip is the default transition for filled and filled-outlined. It uses the horizontal FlipDown-style rotor: the upper leaf rotates around the horizontal center axis and reveals the next value on its reverse face.

fade is available with every appearance. It fades the complete digit in and out, without using a rotor. The full fade lasts 650 ms, the same duration as the flip transition.

outlined and plain never use a rotor. When animation="flip" is requested with either appearance, the component automatically resolves the transition to fade.

<!-- FlipDown-style transition -->
<lgs1920-countdown
    appearance="filled-outlined"
    animation="flip"
    target-date="2026-12-31T23:59:59+01:00"
></lgs1920-countdown>

<!-- Fade transition with a filled card -->
<lgs1920-countdown
    appearance="filled"
    animation="fade"
    target-date="2026-12-31T23:59:59+01:00"
></lgs1920-countdown>

<!-- The requested flip is automatically replaced by fade -->
<lgs1920-countdown
    appearance="outlined"
    animation="flip"
    target-date="2026-12-31T23:59:59+01:00"
></lgs1920-countdown>

<!-- Plain appearance always uses fade -->
<lgs1920-countdown
    appearance="plain"
    animation="flip"
    target-date="2026-12-31T23:59:59+01:00"
></lgs1920-countdown>

Theme integration

The component inherits Web Awesome color, typography, spacing, border, and radius tokens. Its default filled surface is derived from --wa-color-brand-fill-quiet, and its default digit color is --wa-color-brand.

The following component properties can be overridden by the host application:

| Custom property | Purpose | Default | | --- | --- | --- | | --lgs-countdown-card-surface | Filled card and rotor background | A mix of --wa-color-brand-fill-quiet and --wa-color-neutral-10 | | --lgs-countdown-card-border | Outlined card border | --wa-color-neutral-border-normal | | --lgs-countdown-brand-color | Digit color | --wa-color-brand | | --lgs-countdown-legend-color | Unit label color | --wa-color-text-normal | | --lgs-countdown-card-radius | Digit card and leaf radius | --wa-panel-border-radius | | --lgs-countdown-digit-gap | Gap between digits in one unit | --wa-space-3xs (2px) | | --lgs-countdown-unit-gap | Gap between Days, Hours, Minutes, and Seconds | clamp(var(--wa-space-m), 4cqi, var(--wa-space-xl)) |

The visible gap between digits in one unit is controlled by --lgs-countdown-digit-gap and defaults to Web Awesome's --wa-space-3xs token (2px). The unit gap is independent from that digit gap. A host application can apply its own spacing or brand values without coupling that data to the component.

The default unit gap is responsive to the countdown's inline size: it grows progressively from --wa-space-m on narrow cards to --wa-space-xl on wide cards. The 4cqi preferred value uses the component's container query width.

The four units always remain on one line. Card widths scale from the available inline size using the three-digit Days maximum, while the small-screen label token keeps unit names readable on narrow devices.

.launch-countdown {
    --lgs-countdown-card-surface: color-mix(in oklab, var(--wa-color-brand-fill-quiet) 72%, var(--wa-color-neutral-10) 28%);
    --lgs-countdown-card-border: var(--wa-color-surface-border);
    --lgs-countdown-brand-color: var(--wa-color-brand);
    --lgs-countdown-legend-color: var(--wa-color-text-normal);
    --lgs-countdown-card-radius: var(--wa-panel-border-radius);
    --lgs-countdown-digit-gap: var(--wa-space-3xs);
}

Demo

Use the live demo directly in your browser. It provides an interactive countdown and lets you change its appearance, animation, language, labels, card ratio, theme, color mode, and brand color to see how the component behaves.

To run the demo locally:

bun install
bun run dev

Open http://localhost:4173.

Controls update the countdown immediately and persist in localStorage.

To reset saved settings, run localStorage.removeItem('lgs1920-countdown-demo-config') in the browser console and reload the page.

GitHub Actions publishes the demo to GitHub Pages when main changes.

Publish on npm

The release script manages the package version and keeps the release displayed above in sync with package.json:

# 1.0.4 -> 1.0.5 (patch is the default)
bun run publish

# 1.0.4 -> 1.1.0
bun run publish --minor

# 1.0.4 -> 2.0.0
bun run publish --major

Preview the proposed version and release notes with bun run publish --preview or bun run publish --minor --preview. The preview makes no changes. After reviewing and validating the proposed text, run bun run publish with the selected increment. The script stops when there are uncommitted changes or when no changes have been made in src or scripts since the last v* tag. When it succeeds, it updates package.json and this README, creates the version commit and annotated tag, then pushes them to main. The tag starts the GitHub Actions workflow, which runs the tests and build, publishes the package to npm with the NPM_TOKEN repository secret, and creates the GitHub release from the validated tag notes with the release summary and comparison link.

License

MIT. See LICENSE.