Expiry Timer
ProA countdown to the moment an approval or permission request lapses: grey while there is time, amber near the end and red once it has expired.
Playground
Installation
Expiry Timer comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import { ExpiryTimer } from "@wunderui/react"Then use it:
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 for
- Approval Card for an approval that already shows its own countdown when you pass an expiry time
- Scope List for the access a request asks for, with the countdown in its header
- Agent Status for how long a run has been going, which counts up
Warning threshold
The warning point is in milliseconds, 60,000 by default. From then on the timer turns amber and announces Expiring soon once, and all four cards start with 1 min 30 s left.
Warn at
Label
You choose the words for Expires in and Expired. The clock is always written the same way.
Duration
The clock reads MM:SS and adds hours from one hour on, as 1:04:32. It never switches to words like 2 min left, so put those in the text around the timer.
Behavior and motion
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
The figure shows the pill in its normal state. The hidden announcement has no number because it cannot be seen.
- 1data-slot="expiry-timer"
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.
- 2
A 14 px timer icon, hidden from assistive technology. It takes the colour of the text.
- 3
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.
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
- 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.
- Do
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.
- Do
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.
- Do
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.
- Do
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
Don't pass the warning time in seconds. It is in milliseconds, and 60 means 60 ms.
- Don’t
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 is a plain component, so this table lists every prop. It passes no other props on to its span.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| expiresAt required | 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. |
| warnAt | number | 60_000 | Milliseconds left at which the pill turns yellow and announces . Default . |
| onExpire | () => void | — | Called once when the time runs out. A new arms it again. |
| label | ReactNode | "Expires in" | The words before the clock. Default . |
| expiredLabel | ReactNode | "Expired" | The words once the time is up. Default . The hidden announcement always says . |
| className | string | — | Extra classes for the pill. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("expiry-timer")The full library index for assistants is at /llms.txt.
Related components
Send 14 payment reminders
Medium riskEmails the contact on every invoice more than 30 days overdue. Sent emails cannot be recalled.
2 min agoPOST /email/bulk to: 14 recipients template: invoice-overdue-30 dry_run: false
AI & Agents5 stylesProApproval CardThe human-in-the-loop gate: what the agent wants to do, how risky it is, approve or reject.Requested access
Expires in- Read the docs appapps/docs · 412 files
- Edit component filespackages/react/src/components · 198 files
- Open a pull requestwunder-ui/wunderui · branch tokens-sync
AI & Agents5 stylesProScope ListWhat an agent asks to access, one scope per row, with a countdown until the request lapses.