wc-timer

A lightweight, dependency-free Web Component for countdowns and elapsed time. It uses the native Intl API for formatting and supports automatic language detection.

Features

Zero Dependencies: Built with standard Web Components API.
Smart Formatting: Supports various presets like hms, dhms, or ydhms.
Performance: Uses a shared global ticker (TickHub) to sync all instances and save CPU.
Light DOM: Renders text directly, making it easy to style with global CSS.
Responsive: Automatically updates when attributes change.

Installation

npm install wc-timer

Usage

Import the script:

import 'wc-timer';
// Or via script tag
// <script type="module" src="path/to/wc-timer.js"></script>

Use the tag in HTML:

<wc-timer target="2025-12-31T23:59:59Z"></wc-timer>

<wc-timer 
  target="2026-01-01T00:00:00Z" 
  preset="dhms" 
  labels="short" 
  compact
  locale="en-US">
</wc-timer>

API Reference

Attributes

Attribute	Type	Default	Description
`target`	`ISO 8601`	`now`	The target date/time (e.g., `2025-12-31T23:59:59Z`).
`preset`	`string`	`auto`	Format preset: `auto`, `hms`, `dhms`, `ydhms`, `date`.
`labels`	`string`	`long`	Unit labels: `none` (00:00:00), `short` (1h 5m), `long` (1 hour 5 minutes).
`compact`	`boolean`	`false`	If present, hides zero-value units (e.g., skips "0 years").
`locale`	`BCP 47`	`auto`	Forces a specific language (e.g., `pl`, `en`, `de`). Defaults to browser settings.

JavaScript Properties

All attributes are reflected as properties on the DOM element.

const el = document.querySelector('wc-timer');

// Update target dynamically
el.target = new Date('2030-01-01');

// Change configuration
el.preset = 'ydhms';
el.compact = true;

Browser Support

Works in all modern browsers supporting Web Components and Intl.DurationFormat (or falls back gracefully).

License

MIT