# Expiry Timer

Countdown until an approval or permission request lapses — amber at the end, red once expired.

- Category: AI & Agents
- Page: https://wunderui.com/components/expiry-timer
- Tier: Core and Pro

## Install

Expiry Timer ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ExpiryTimer } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { ExpiryTimer } from "@wunderui/react"

export function RequestTimer() {
  const [expiresAt] = useState(() => new Date(Date.now() + 5 * 60_000))
  return <ExpiryTimer expiresAt={expiresAt} onExpire={() => console.log("expired")} />
}
```

Expected result: You see a grey pill with a timer icon and Expires in 05:00 counting down each second. With a minute left it turns yellow, and at zero it turns red and reads Expired.

## When to use

### Use Expiry Timer for

- The time left on an approval or permission request that lapses
- A session or a token that ends, with a warning before it does
- A queue of pending requests, one timer each

### Use something else

- [Approval Card](https://wunderui.com/components/approval-card) for an approval that already shows its own countdown when you pass an expiry time
- [Scope List](https://wunderui.com/components/scope-list) for the access a request asks for, with the countdown in its header
- [Agent Status](https://wunderui.com/components/agent-status) for how long a run has been going, which counts up

## Behavior

How the timer reads the clock, when it changes colour and what it says out loud.

- **Clock:** Once a second the timer reads the deadline against the browser clock. Time left is written MM:SS, or H:MM:SS from one hour on, and never switches to words such as 2 min left.
- **States:** The pill is grey above the warning time (60,000 ms by default), yellow at or under it, and red with the expired label at zero. Changes are found on a tick, so they can be up to a second late.
- **Announcements:** The clock is never read out. A hidden polite region says Expiring soon at yellow and Expired at red, once each, and a timer that mounts inside the warning window says Expiring soon right away.
- **onExpire:** The expire callback is called once when the time runs out. A new deadline, such as a renewed request, arms it again, and a deadline in the past calls it right after the first reading.
- **Before the first reading:** The server render and the first client render show the label without a time, because the clock is not read until the first effect. The reading follows within a frame.
- **Invalid deadline:** A deadline that is not a valid date shows the label without a time, never changes state and never calls the expire callback.
- **Colour and words:** The state is also written: the pill reads Expired when it is over, and the warning is announced, so colour is not the only signal.
- **Motion:** None. The figures change once a second and the colour changes at once.
- **Reduced motion:** Nothing changes with reduced motion: there is no animation to switch off, and the text and announcements are the same.

## Anatomy

- `ExpiryTimer`: An inline pill with a fully rounded shape, 12 px medium text and tabular figures. It is a timer that never announces itself, and its state is normal, warning or expired.
- `Icon`: A 14 px timer icon, hidden from assistive technology. It takes the colour of the text.
- `Label and time`: The label and the clock, such as Expires in 04:32, or the expired label once the time is up. The pill is grey in the normal state, yellow under the warning time and red when expired.
- `Announcement`: A visually hidden polite live region inside the pill. It reads Expiring soon or Expired once when the state changes, and never counts.

## Best practices

### When to use

- Use an Expiry Timer for the countdown on a request that lapses, such as a permission request or a session. Approval Card and Scope List count down by themselves when you pass them an expiry time.

### Do

- Keep the deadline in state or on the request, not in the render. Building a new date in the render gives a new deadline on every render, so the countdown never gets anywhere.
- Handle the expire callback by changing the request itself, for example by marking it expired and switching off Approve. The timer shows the time and calls it once, but stops nothing.
- When the request expires, say what to do next in a status line, such as asking the agent to send it again. The timer announces Expired and no more.
- Offer a way forward at the end: a new request with a new deadline, or an extension. A new expiry time starts the countdown again and may expire again.
- Set the warning time to what a person needs to react, in milliseconds. 60,000 suits a quick approval; a session that needs a decision may need 120,000.

### Don't

- Don't announce the countdown yourself. The timer is silent every second on purpose, and a second live region that reads the time would read it every second.
- Don't pass the warning time in seconds. It is in milliseconds, and 60 means 60 ms.
- Don't treat the pill as the lock. It runs on the visitor's clock, so check the deadline on the server as well.

## API reference

### ExpiryTimer

| Prop | Type | Default | Description |
|---|---|---|---|
| expiresAt* | Date \| string \| number |  | The deadline: a Date, an ISO string or a timestamp in milliseconds. Keep it in state; a new value starts the countdown again. |
| className | string |  | Extra classes for the pill. |
| expiredLabel | React.ReactNode | "Expired" | The words once the time is up. Default `Expired`. The hidden announcement always says `Expired`. |
| label | React.ReactNode | "Expires in" | The words before the clock. Default `Expires in`. |
| onExpire | () => void |  | Called once when the time runs out. A new `expiresAt` arms it again. |
| warnAt | number | 60_000 | Milliseconds left at which the pill turns yellow and announces `Expiring soon`. Default `60000`. |

## Examples

### Warn at: how long before the end the timer turns amber

### Label: the words before the time and after the end

### Duration: how the clock is written

## In context

### Approval request: it lapses, and a new request starts a new deadline

The request lasts 25 seconds and turns amber from 15. When it runs out, Approve and Reject switch off and Ask again sends a new one, and the status line says what to do next.

### Session: extend it before it ends

The session turns amber with two minutes left. Stay signed in sets a new deadline 15 minutes away, and when the session ends the button becomes Sign in again.

### Pending requests: one timer each

Three requests with their own deadlines, the last one already amber. Each timer reports its expiry once, and the summary counts what is left.

## For AI agents

`get_component("expiry-timer")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
