# Relative Time

> A live relative timestamp: "just now", "42 seconds ago", "in 2 hours", "yesterday", then the date past a cutoff. Every instance shares one clock and re-renders only when its text changes, days follow the calendar, and hover shows the exact moment in local time, UTC and Unix. Long, short or narrow in any locale, with no hydration mismatch.

- Slug: `relative-time`
- Category: [Numbers](https://www.assembli.design/category/numbers.md)
- Type: component
- Tags: time, date, timestamp, relative, ago, intl, format, live
- npm dependencies: @base-ui/react
- shadcn/ui dependencies: none
- Live preview: https://www.assembli.design/preview/relative-time
- Page: https://www.assembli.design/components/relative-time

![Relative Time preview](https://www.assembli.design/thumbnails/relative-time-light.png)

## Props

Other props pass through to the root element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `locale` | `string` |  |  |
| `style` | `RelativeTimeStyle` | `"long"` |  |
| `dateAfterDays` | `number` | `7` | Past this many days, show the date instead ("Oct 12", or "Oct 12, 2024" in another year). `Infinity` never does. |
| `nowWithin` | `number` | `10` | Within this many seconds of now, say "just now" (or "now" for narrow). |
| `date` (required) | `DateInput` |  |  |
| `tooltip` | `boolean` | `true` | Shows the full date, UTC and Unix time on hover or focus. Defaults to `true`. |
| `focusable` | `boolean` | `false` | Lets keyboard users tab to the timestamp to read its tooltip. |
| `animate` | `boolean` | `true` | Eases each new value in. Defaults to `true`; off under reduced motion. |

## Install

One-time setup (needs a subscription):

1. Add the registry to the project's `components.json`: `{"@assembli":{"url":"https://www.assembli.design/r/{name}.json","headers":{"Authorization":"Bearer ${ASSEMBLI_API_KEY}"}}}` (merge into `"registries"`).
2. Put an API key from https://www.assembli.design/account in `.env.local` as `ASSEMBLI_API_KEY=asm_…`.

Then install with the shadcn CLI (writes `components/relative-time/relative-time.tsx` and installs dependencies):

```bash
npx shadcn@latest add @assembli/relative-time
```

Registry item JSON: https://www.assembli.design/r/relative-time.json (send `Authorization: Bearer <api key>`)

## Code

> Component source needs an Assembli subscription ($12/month or $96/year) and an API key sent as `Authorization: Bearer <key>`. To get one without copying anything, POST https://www.assembli.design/api/agent/login (or call the MCP tool connect_account), show the user the link it returns, and poll https://www.assembli.design/api/agent/token for the key. Or subscribe at https://www.assembli.design/pricing and create a key at https://www.assembli.design/account.