# Relative time

"3 minutes ago" / "in 6 days", kept fresh, with the exact time on hover. Shows the date until the clock is known. `format` shows an absolute time instead ("5 Nov 2026, 14:03"), in the locale, with the same server-safe gate.

- Registry name: `relative-time` (`@candor/relative-time`)
- Tier: Free (MIT). No licence key needed.
- Docs: https://candor.themethodic.com/docs/relative-time

## Install

```bash
npx candor-ui add relative-time
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/relative-time`.
It brings in: locale.

## Example

```tsx
"use client"

import { RelativeTime } from "@/components/relative-time"

const minutesAgo = (m: number) => new Date(Date.now() - m * 60_000)

export default function Example() {
  return (
    <ul className="flex flex-col gap-1 text-sm">
      <li>Sent <RelativeTime date={minutesAgo(0.2)} /></li>
      <li>Updated <RelativeTime date={minutesAgo(14)} /></li>
      <li>Created <RelativeTime date={minutesAgo(60 * 30)} /></li>
    </ul>
  )
}
```

## <RelativeTime>

Props:

- `date: Date | string`: When it happened. Shown as "5 minutes ago", with the exact time on hover.
- `bare?: boolean | undefined` (default `false`): Drop "ago" and "in", for tight spaces: "5 minutes".
- `format?: "relative" | DateStyle | undefined` (default `"relative"`): "relative" (the default), or an absolute "date", "datetime" or "time" in the locale.
- `className?: string | undefined`

## Functions

### formatRelative

```ts
formatRelative(date: Date, now = new Date(), { locale, justNow = relativeTimeStrings.justNow, bare = false }: { locale?: string | undefined; justNow?: string | undefined; bare?: boolean | undefined } = {})
```

"5 minutes ago", "in 6 days", in the locale (the runtime's own when left out). `bare` drops the direction for tight spaces: "5 minutes".

### useNow

```ts
useNow()
```

The current time in milliseconds, updated every 30 seconds; null while rendering on the server.

## Strings (`relativeTime`)

The fixed words, English by default. Override any of them under `relativeTime` in `<LocaleProvider strings={{ relativeTime: { … } }}>`; the table is exported as `relativeTimeStrings`.

- `justNow`: just now

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.