Countdown
StableA deadline as a large date, the days left in words, and an optional bar of time used.
Also known as timer, deadline, time remaining
Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.
With a time bar
They must reply by
20 days left
<Countdown className="w-full max-w-sm" deadline="2026-10-27" today="2026-10-07" start="2026-09-27" label="They must reply by" />A start date adds the bar. The bar has the words 10 of 30 days used for screen readers.
When to use it
Answers the first question about a case: by when. The date is the largest text and the days left are written out, so nothing depends on colour or a bar.
Made of: Label · Action chip · Date · Days in words · Time bar
Use it for
- A reply-by or pay-by date at the top of a case.
- A deadline with a start date, to show how much time has gone.
- A missed deadline that now needs a person to take a step.
Do and avoid
They must reply by
20 days left
They must reply by
Due soon20 days left
Do
- Put it near the top, since the date is the first thing people look for.
- Pass start when the person needs to see how much time has gone.
- Use needsAction only when the next step belongs to a person.
Avoid
- Do not use amber because a date is close. Use it when a person must act.
- Do not rely on the bar. The days are always written in words.
- Do not use it for dates measured in hours or minutes.
On a phone
- It is a card that fills its container, with the date in large text that breaks anywhere if it is too long.
- The days left are in words and the bar is a picture of the same thing, so a small screen loses nothing.
- Nothing in it is tapped or hovered.
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| deadlinerequired | string | none | ISO date, such as 2026-10-27. Only the calendar day is used. |
| today | string | none | ISO date to count from. Defaults to today on the device. Pass it in docs and tests. |
| labelrequired | string | none | What the date is, such as They must reply by. Also the name of the group. |
| start | string | none | ISO date the clock started. Turns on the time bar. |
| unit | "days" | "days" | Only days for now. |
| missedLabel | string | "Deadline passed" | Shown with an icon once the deadline has passed. |
| formatDate | (iso: string) => string | long date in en-IN | Turns the ISO date into the large text. |
| needsAction | boolean | none | Adds the amber chip. When the deadline is today or past it also adds an amber border and bar. Leave it off unless a person must act. |
| actionText | string | "Needs action" | Text of the amber chip. |
| className | string | none | Classes for the outer card. |
"Show code under the preview gives the code for the example on the stage."
In Figma
In Figma, one Countdown switches all of this from its properties panel, across 2 variants. Each property sets the React prop beside it, so design and code use the same names.
| Figma property | React | Values |
|---|---|---|
| Needs action | needsAction | On or off |
| Label | label | Any text |
States
States this part has beyond its default look. Build each one your screen can reach. States set by a property are in the Code tab.
- days left
- The default. The date is large and the days left are written in words.
- due today
- When the deadline is today the line reads Due today.
- missed
- After the deadline the missed label shows with an icon, followed by the days past.
- needs action
- With needsAction, an amber chip shows. If the deadline is today or past, the border and bar turn amber too.
- no date
- If the deadline cannot be read as a date, an em dash shows in place of the date and the days line is left out.
Tokens
Change one of these and every part that uses it follows.
--surface--border--attention--attention-soft--attention-fg--fg--fg-muted--radius-control--radius-card
Built in
- The card is a group named by the label.
- The date is a time element with the ISO date.
- Days left, due today and days past are written in words, so colour is never the only cue.
- A missed deadline shows an icon and the missed label.
- The time bar is a meter with the text N of M days used.
- Dates are worked out from the calendar day only, so time zones and daylight saving cannot shift the count.
What you need to do
- Give a label that says whose date it is, such as They must reply by.
- Pass needsAction only when a person has to act. Amber is not decoration.
- Pass today in docs and tests so the days left do not change under you.
Built toward WCAG 2.2 AA and checked automatically; no independent audit yet. Read the accessibility guide