CountdownTimer

When to use

When something will expire and people need to know: a one-time code’s validity, a resend wait, a session timeout warning.

When not to use

• For past time: Write “2 minutes ago” with DateTimeText.
• For progress: Show progress tied to work, not time, with Meter or a progress bar.
• To pressure people: Do not add a countdown without a real time limit.

Anatomy

01:3001:30

LightDark

Copy code

import { CountdownTimer, Provider } from '@bigbang/ui';
import { useState } from 'react';

export default function Default() {
  const [target] = useState(() => Date.now() + 90_000);
  return (
    <Provider locale="en-GB">
      <div className="flex flex-wrap items-center gap-xl">
        <CountdownTimer target={target} label="Code expiry" />
        <CountdownTimer target={target} label="Code expiry" variant="ring" duration={120} warnAt={30} />
      </div>
    </Provider>
  );
}

1. Ring (optional): Drains clockwise over duration.
2. Clock: “01:05”; “1:02:05” past an hour.
3. Status region (hidden): Reads the milestones.

Behaviour

• The target is a moment (target), so a reload does not reset the time. Take it from the server.
• The clock is recalculated every 250 ms, so it shows the right second after returning from a background tab.
• It turns to the warning colour at warnAt and to the subtle colour at zero; the colours fade.
• Screen readers hear not every second but the announceAt moments: by default 5 minutes, 1 minute, 10 seconds and “Time is up”.
• onComplete is called once when time runs out.
• To start a new period, pass a new target with a key.

Guidelines

• Say next to the timer what it counts, and name it with label.
• Say what happens when time is up and what can be done (send again, extend the session).
• For session timeouts, give people a way to extend the time (WCAG 2.2.1).

Content

Key	TR	EN
ui.countdown-timer.minutes-left	{count} dakika kaldı	{count} min left
ui.countdown-timer.seconds-left	{count} saniye kaldı	{count} s left
ui.countdown-timer.done	Süre doldu	Time is up

Related components

• OtpInput: Where the code is typed.
• DateTimeText: Past and future times.