v0.1.0

<hf-countdown>Custom elementFeedbackFree

Countdown

HH:MM:SS countdown set over a dot grid; changed digits roll over as their tile reprints, the last ten seconds turn red and zero bursts.

View as Markdown

<hf-countdown>· loading

Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

Loading <hf-countdown>

Props

secondsremounts

loopremounts

labelremounts

<HfCountdown seconds={8049} label="Usage resets in" />

Installation

pnpm dlx shadcn@latest add @lumesec/hf-countdown

First timeRegister the @lumesec registry once, or install by URL+

Adds @lumesec to your components.json:

pnpm dlx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json

Or skip the setup and install by URL:

npx shadcn@latest add https://elements.lumesec.ai/r/hf-countdown.json

Usage

import { HfCountdown } from "@/components/lumesec/hf-countdown";

export function Example() {
  return (
    <HfCountdown seconds={8049} label="Usage resets in" />
  );
}

Behaviour

Each digit sits on its own dotted tile; when it changes, the digit rolls over and a bright line prints through the tile from top to bottom. The last ten seconds turn red, and zero bursts.

API reference

Attributes

secondsReact propsecondsTypenumberDefault8049

Starting duration in seconds (8049 is 2 h 14 min 9 s). Read on connect and by restart().

loopReact proploopTypebooleanDefaultfalse

Presence attribute. Restarts from seconds 1.6 s after reaching zero.

labelReact proplabelTypestringDefaultUsage resets in

Text above the digits; it also names the timer.

Events

Events bubble and cross the shadow boundary unless the description says otherwise.

doneReact proponDoneDetail{}

Fires once when the countdown reaches zero.

Methods

Call them on the element, for example through a React ref.

restart(seconds?: number)

Starts again from seconds, or from the seconds attribute when omitted, and updates the end time in the header.

Properties

remaining (read-only)Typenumber

Whole seconds left.

Accessibility

The digits are text in the monospace font with tabular figures, inside an element with role="timer" named by the label through aria-labelledby. A timer is not a live region, so the seconds are not announced; the dot canvas is aria-hidden.
The header shows the end time as text, for example at 4:30 PM.
Reduced motion: digits change without rolling and their tiles do not reprint, the colons do not pulse, the urgent tiles do not pulse and no sparks are drawn.

Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from --lumesec. See Theming.

This component reads --destructive, --foreground, --lumesec, --lumesec-success and --muted-foreground.

To restyle only LumeSec elements, set the matching --ui-* overrides: --ui-accent, --ui-danger, --ui-fg, --ui-mono, --ui-muted and --ui-ok.

Notes

The countdown runs against the wall clock from the moment it connects, so it keeps time while off-screen.
done is emitted from the render loop, which pauses off-screen; if the element is not visible at zero, done fires when it scrolls back into view.
Between digit changes the loop sleeps until the next whole second instead of drawing every frame; during the last ten seconds it animates continuously.
Attributes are not observed; call restart() after changing seconds.

<hf-progress>

Progresshf-progress

<hf-context>

Context windowhf-context

<hf-gauge>

Gaugehf-gauge

<hf-rings>

Goal ringshf-rings

Was this page helpful?

Related