Countdown Timer

A flexible progress-aware countdown (or count-up) timer with four display variants, five sizes, configurable color thresholds, pause/resume/reset controls, and an imperative ref API for external control.

Basic Circular Timer

A 30-second circular countdown. Progress ring shrinks as time runs out. Pause and reset via the controls below.

30sec

Event: —

import { CountdownTimer } from 'fluxo-ui';

<CountdownTimer
  duration={30}
  variant="circular"
  size="md"
  onComplete={() => console.log('Done!')}
/>

Shape Variants

Three SVG border-progress shapes: circular ring, rounded square, and equilateral triangle.

Circular

01:00min

Rounded Square

01:00min

Triangle

01:00min

Other Variants

Linear bar, segmented blocks, and large numeric digit display.

Linear

01:00100%

Segmented (20 blocks, single uniform row)

01:00

Numeric

01h:02m:03s

// Circular — ring arc progress
<CountdownTimer duration={60} variant="circular" />

// Rounded Square — rounded rectangle border progress
<CountdownTimer duration={60} variant="rounded-square" />

// Triangle — equilateral triangle border progress
<CountdownTimer duration={60} variant="triangle" />

// Linear — horizontal bar progress
<CountdownTimer duration={60} variant="linear" />

// Segmented — equal blocks that disappear one by one
<CountdownTimer duration={60} variant="segmented" segmentCount={20} />

// Numeric — styled digit display
<CountdownTimer duration={3723} variant="numeric" />

Sizes

Five sizes from xs to xl — applies to all variants.

01:00min

<CountdownTimer duration={60} variant="circular" size="xs" />
<CountdownTimer duration={60} variant="circular" size="sm" />
<CountdownTimer duration={60} variant="circular" size="md" />
<CountdownTimer duration={60} variant="circular" size="lg" />
<CountdownTimer duration={60} variant="circular" size="xl" />

Color Thresholds

Watch the auto-shift timer below — it starts primary blue, turns warning amber at ≤66% remaining, then danger red at ≤33%. Set repeat so you can observe the full cycle.

Auto-shift (repeat)

20sec

Success

20sec

Warning

20sec

Danger

20sec

Custom #8b5cf6

20sec

// Auto color-shift: primary → warning → danger as time runs out
// 'at' means "when remaining % is AT OR BELOW this value"
<CountdownTimer
  duration={20}
  variant="circular"
  colorThresholds={[
    { at: 66, color: 'warning' },  // ≤66% left → warning amber
    { at: 33, color: 'danger' },   // ≤33% left → danger red
  ]}
  repeat
/>

// Static semantic colors
<CountdownTimer duration={20} variant="circular" color="success" />
<CountdownTimer duration={20} variant="circular" color="warning" />
<CountdownTimer duration={20} variant="circular" color="danger" />

// Custom hex color
<CountdownTimer duration={20} variant="circular" color="#8b5cf6" />

Count-Up Mode

Instead of counting down, elapsed time fills up the progress from 0 to the target duration.

0sec

// Count up from 0 → duration (elapsed timer)
<CountdownTimer
  duration={60}
  variant="circular"
  countUp={true}
  onComplete={() => alert('60 seconds elapsed!')}
/>

Repeat & Auto-Start

Use repeat to loop infinitely on completion. Use autoStart={false} to let the user start manually.

Repeat (15s loop)

15sec

Manual Start

30sec

// Repeat: automatically restarts when completed
<CountdownTimer duration={15} repeat={true} />

// Manual start: does not start until you press play
<CountdownTimer duration={30} autoStart={false} />

Pause on Hover

Hover over the timer to pause it automatically — useful in interactive UIs where the user might need a moment.

01:00min

// Pauses automatically while the user hovers over the timer
<CountdownTimer
  duration={60}
  variant="circular"
  pauseOnHover={true}
/>

Disabled State

Disable the timer entirely and show a custom badge message. All interaction is blocked.

Default "Off"

Off

30sec

Custom message

Unavailable

30sec

Linear disabled

Not active

30100%

// Disabled with default "Off" label
<CountdownTimer duration={30} disabled />

// Disabled with custom message
<CountdownTimer duration={30} disabled disabledMessage="Unavailable" />

Long Durations

When duration exceeds 60s the display auto-promotes to minutes, hours, or days. Pass seconds only.

2h circular

02:00hrs

1.5 days numeric

01d:12h:00m:00s

90 min linear

01:30100%

// 2 hours = 7200 seconds → displays "02:00 hrs"
<CountdownTimer duration={7200} variant="circular" />

// 1.5 days = 129600 seconds → displays days + hours
<CountdownTimer duration={129600} variant="numeric" />

// 90 minutes = 5400 seconds → displays "01:30 min"
<CountdownTimer duration={5400} variant="linear" />

Imperative Control via Ref

Expose timer controls to parent components using a forwarded ref. Hide the built-in controls and drive the timer externally.

30sec

import { useRef } from 'react';
import { CountdownTimer } from 'fluxo-ui';
import type { CountdownTimerHandle } from 'fluxo-ui';

const timerRef = useRef<CountdownTimerHandle>(null);

<CountdownTimer ref={timerRef} duration={30} autoStart={false} showControls={false} />

<button onClick={() => timerRef.current?.start()}>Start</button>
<button onClick={() => timerRef.current?.pause()}>Pause</button>
<button onClick={() => timerRef.current?.resume()}>Resume</button>
<button onClick={() => timerRef.current?.reset()}>Reset</button>

Import

import { CountdownTimer } from 'fluxo-ui';
import type { CountdownTimerProps, CountdownTimerHandle } from 'fluxo-ui';

Props

PropertyTypeDefaultDescription

durationreq

number

—

Total duration in seconds.

durationreq

number

Total duration in seconds.

variant

"'circular'"

Visual display style.

variant

Visual display style.

size

'xs' | 'sm' | 'md' | 'lg' | 'xl'

"'md'"

Size of the timer control.

size

'xs' | 'sm' | 'md' | 'lg' | 'xl'"'md'"

Size of the timer control.

autoStart

boolean

true

Start the timer immediately on mount.

autoStart

booleantrue

Start the timer immediately on mount.

repeat

boolean

false

Automatically restart when completed.

repeat

booleanfalse

Automatically restart when completed.

countUp

boolean

false

Count up from 0 to duration instead of counting down.

countUp

booleanfalse

Count up from 0 to duration instead of counting down.

color

'primary' | 'success' | 'warning' | 'danger' | string

"'primary'"

Static color for the progress indicator. Accepts semantic names or any CSS color.

color

'primary' | 'success' | 'warning' | 'danger' | string"'primary'"

Static color for the progress indicator. Accepts semantic names or any CSS color.

colorThresholds

ColorThreshold[]

—

Array of { at: number (%), color } breakpoints for auto color-shifting.

colorThresholds

ColorThreshold[]

Array of { at: number (%), color } breakpoints for auto color-shifting.

segmentCount

number

20

Number of segments for the segmented variant.

segmentCount

number20

Number of segments for the segmented variant.

showControls

boolean

true

Show the built-in pause and reset buttons.

showControls

booleantrue

Show the built-in pause and reset buttons.

pauseOnHover

boolean

false

Automatically pause when the user hovers over the timer.

pauseOnHover

booleanfalse

Automatically pause when the user hovers over the timer.

disabled

boolean

false

Disable the timer — no interaction, shows disabled badge.

disabled

booleanfalse

Disable the timer — no interaction, shows disabled badge.

disabledMessage

string

"'Off'"

Badge text shown when disabled.

disabledMessage

string"'Off'"

Badge text shown when disabled.

pulseWhenRunning

boolean

false

Apply a subtle pulse animation to the time display while running.

pulseWhenRunning

booleanfalse

Apply a subtle pulse animation to the time display while running.

announceInterval

number

—

Announce the remaining time via aria-live region every N seconds (e.g. 60 for once-per-minute).

announceInterval

number

Announce the remaining time via aria-live region every N seconds (e.g. 60 for once-per-minute).

announceFinalSeconds

number

—

When remaining seconds drops to or below this value, announce every second via aria-live (e.g. 10 for the final ten-second countdown).

announceFinalSeconds

number

When remaining seconds drops to or below this value, announce every second via aria-live (e.g. 10 for the final ten-second countdown).

announceOnComplete

boolean

false

Announce 'Timer complete' via aria-live region when the timer reaches zero.

announceOnComplete

booleanfalse

Announce 'Timer complete' via aria-live region when the timer reaches zero.

announcePoliteness

'polite' | 'assertive'

"'polite'"

aria-live politeness for the announcement region.

announcePoliteness

'polite' | 'assertive'"'polite'"

aria-live politeness for the announcement region.

criticalThreshold

number

—

Fire onCriticalThreshold once when remaining seconds first drops to or below this value.

criticalThreshold

number

Fire onCriticalThreshold once when remaining seconds first drops to or below this value.

onCriticalThreshold

(remaining: number) => void

—

Called the first time remaining time crosses criticalThreshold (resets on reset/restart).

onCriticalThreshold

(remaining: number) => void

Called the first time remaining time crosses criticalThreshold (resets on reset/restart).

className

string

—

Additional CSS class name.

className

string

Additional CSS class name.

style

React.CSSProperties

—

Inline style override.

style

React.CSSProperties

Inline style override.

onComplete

() => void

—

Called when the timer reaches zero (or duration in count-up mode).

onComplete

() => void

Called when the timer reaches zero (or duration in count-up mode).

onTick

(remaining: number, elapsed: number) => void

—

Called every second with remaining and elapsed values.

onTick

(remaining: number, elapsed: number) => void

Called every second with remaining and elapsed values.

onPause

(remaining: number) => void

—

Called when the timer is paused.

onPause

(remaining: number) => void

Called when the timer is paused.

onResume

(remaining: number) => void

—

Called when the timer resumes.

onResume

(remaining: number) => void

Called when the timer resumes.

onReset

() => void

—

Called when the timer is reset.

onReset

() => void

Called when the timer is reset.

Ref Handle (CountdownTimerHandle)

PropertyTypeDefaultDescription

start()

function

—

Start the timer if not already running.

start()

function

Start the timer if not already running.

pause()

function

—

Pause the timer.

pause()

function

Pause the timer.

resume()

function

—

Resume a paused timer.

resume()

function

Resume a paused timer.

reset()

function

—

Reset to initial value. Restarts automatically if autoStart is true.

reset()

function

Reset to initial value. Restarts automatically if autoStart is true.

6 Variants

Circular ring, rounded square, triangle, linear bar, segmented blocks, and pure numeric digit display.

5 Sizes

From compact xs to large xl — all variants scale uniformly.

Color Thresholds

Define percentage breakpoints to automatically shift color as urgency increases.

Count-Up / Count-Down

Switch between elapsed timer and deadline countdown with a single prop.

Repeat & Auto-Start

Loop the timer infinitely and control whether it starts on mount or on demand.

Pause on Hover

Automatically pauses the timer when the user mouses over it.

Imperative Ref

Control start, pause, resume, and reset from parent code via a forwarded ref handle.

Disabled State

Disable the timer with a customizable badge message (defaults to "Off").

Smart Time Format

Automatically promotes display from seconds → minutes → hours → days based on duration.