Timer·component·@astryxdesign/core

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.

Open in Playground @astryxdesign/core/Timer

Showcases and examples

4 documented examples

Timer

Timer API entry

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · timer-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {useState} from 'react';
import {Timer} from '@astryxdesign/core/Timer';
import {Stack} from '@astryxdesign/core/Layout';
import {Text} from '@astryxdesign/core/Text';

export default function TimerShowcase() {
  const [startedAt] = useState(() => Date.now() - 3_753_000);

  return (
    <Stack direction="vertical" gap={4}>
      <Text type="large" color="primary" weight="semibold">
        Processing
      </Text>
      <Stack direction="horizontal" gap={6} vAlign="center">
        <Stack direction="vertical" gap={1}>
          <Text type="supporting" color="secondary">
            Elapsed
          </Text>
          <Timer
            startTime={startedAt}
            type="body"
            size="xl"
            color="primary"
            weight="semibold"
          />
        </Stack>
        <Stack direction="vertical" gap={1}>
          <Text type="supporting" color="secondary">
            Clock
          </Text>
          <Timer
            format="clock"
            startTime={startedAt}
            type="body"
            size="xl"
            color="primary"
            weight="semibold"
          />
        </Stack>
      </Stack>
    </Stack>
  );
}

Usage

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.
Do not use Timer for dates, time zones, or relative calendar language; use Timestamp instead.
Do not add aria-live unless hearing an announcement every tick is appropriate for the specific task.

Typed props

Prop	Type and behavior
`startTime`	`number` Unix time in milliseconds when the measured operation began. Omit it to start from this Timer's mount.
`format`	`'elapsed' \| 'clock'` · default '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'` · default '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'` · default '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.

Anatomy

Elapsed time · required

Semantic time element containing a standardized elapsed duration.

Theming

Targets

astryx-timer