Timer
Displays a standardized elapsed duration for active work without scheduling a React render on every tick. Elapsed format updates by second below one hour and by minute after one hour; clock format remains second-precise.
Installation
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
Requires React 19+, base CSS and a Theme provider. See Setup.
Timer
Displays a standardized elapsed duration for active work without scheduling a React render on every tick. Elapsed format updates by second below one hour and by minute after one hour; clock format remains second-precise.
| Prop | Type | Default | Description |
|---|---|---|---|
| startTime | number | Unix time in milliseconds when the measured operation began. Omit it to start from this Timer's mount. | |
| format | 'elapsed' | 'clock' | 'elapsed' | Standard duration representation. Elapsed uses compact units and drops seconds after one hour; clock uses m:ss or h:mm:ss. |
| type | 'body' | 'large' | 'label' | 'supporting' | 'code' | 'display-1' | 'display-2' | 'display-3' | 'inherit' | 'supporting' | Semantic text type. Uses the same typography behavior as Timestamp. |
| size | '4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | Explicit font size override. Overrides the size from type. | |
| color | 'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit' | 'secondary' | Text color. |
| weight | 'normal' | 'medium' | 'semibold' | 'bold' | Font weight override. | |
| xstyle | StyleXStyles | StyleX styles for the Text wrapper. Must be a stylex.create() value. | |
| className | string | CSS class name for the Text wrapper. Prefer xstyle for styling. | |
| style | CSSProperties | Inline styles for the Text wrapper. Prefer xstyle for styling. |
Usage guidance
- Use elapsed for compact duration text that may span seconds, minutes, or hours.
- Use clock for stopwatch-like surfaces where seconds remain meaningful after an hour.
- Pass startTime when the operation began before Timer mounted so the display reflects the complete wait.
- Avoid: Do not use Timer for dates, time zones, or relative calendar language; use Timestamp instead.
- Avoid: Do not add aria-live unless hearing an announcement every tick is appropriate for the specific task.
Elapsed duration
<Timer />
Stopwatch clock
<Timer format="clock" />
Operation that started before mount
<Timer startTime={operationStartedAt} />
Match surrounding text
<Text>
Processing for <Timer type="inherit" color="inherit" />
</Text>
Prominent elapsed time
<Timer type="body" size="lg" color="primary" weight="semibold" />
Theming API
{
"targets": [
{
"className": "astryx-timer"
}
]
}
Anatomy
- Elapsed time: Semantic time element containing a standardized elapsed duration.
Examples
- Timer:
- Timer — Formats: Elapsed compact units and stopwatch clock notation shown from the same start time.
- Timer — Inline: A Timer composed into status copy while inheriting the surrounding typography.
- Timer — Typography: Timer using its Timestamp-matched default typography and an emphasized override.