# Timer

- Page: https://jiguang132.com/resources/astryx/docs/timer
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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

```bash
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](/resources/astryx/docs/getting-started).

## 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

```tsx
<Timer />
```

### Stopwatch clock

```tsx
<Timer format="clock" />
```

### Operation that started before mount

```tsx
<Timer startTime={operationStartedAt} />
```

### Match surrounding text

```tsx
<Text>
  Processing for <Timer type="inherit" color="inherit" />
</Text>
```

### Prominent elapsed time

```tsx
<Timer type="body" size="lg" color="primary" weight="semibold" />
```

### Theming API

```json
{
  "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.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt