# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<RelativeTime>`
URL: https://generaltranslation.com/en-GB/docs/react/reference/components/relative-time.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Format localised relative time, such as 2 hours ago. API reference for the `<RelativeTime>` component.

The `<RelativeTime>` component renders relative-time wording using the unit and phrasing conventions of the active locale. It works either by auto-selecting the most appropriate unit from a `Date`, or from an explicit value and unit.

*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.*

## Overview [#overview]

Pass a `Date` as children and `<RelativeTime>` picks the most appropriate unit and formats the time relative to `baseDate`.

```tsx
<RelativeTime>{someDate}</RelativeTime>
// Output: "2 hours ago"
```

All formatting is handled locally with [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat).

*Note: `<RelativeTime>` can cause React hydration errors in server-rendered apps. See [Avoiding hydration errors](#hydration).*

## How it works [#how-it-works]

* **Two modes.** Provide a `Date` (via `children` or `date`) and the component automatically selects the most appropriate unit relative to `baseDate`, or provide an explicit `value` and `unit`, mirroring `Intl.RelativeTimeFormat`.
* **Local formatting.** The relative time is computed and formatted in the browser; the value is never sent to the General Translation API.
* **Renders nothing without input.** If neither a date nor a value is provided, the component renders `null`.

## Props [#props]

| Prop                     | Description                                                         | Type                             | Optional | Default                              |
| ------------------------ | ------------------------------------------------------------------- | -------------------------------- | -------- | ------------------------------------ |
| [`children`](#children)  | A `Date` from which to calculate relative time.                     | `Date`                           | Yes      | —                                    |
| [`date`](#date)          | A `Date` from which to calculate. Takes precedence over `children`. | `Date`                           | Yes      | —                                    |
| [`value`](#value)        | Explicit numeric amount. Requires `unit`.                           | `number`                         | Yes      | —                                    |
| [`unit`](#unit)          | Time unit, used with `value`.                                       | `Intl.RelativeTimeFormatUnit`    | Yes      | —                                    |
| [`baseDate`](#base-date) | Date against which to measure.                                      | `Date`                           | Yes      | `new Date()`                         |
| [`options`](#options)    | `Intl.RelativeTimeFormat` options.                                  | `Intl.RelativeTimeFormatOptions` | Yes      | `{ numeric: 'auto', style: 'long' }` |
| [`locales`](#locales)    | Locale override for formatting.                                     | `string[]`                       | Yes      | Active locale                        |
| [`name`](#name)          | Variable name for the entry.                                        | `string`                         | Yes      | —                                    |

### `children` [#children]

**Type** `Date` · **Optional**

A `Date` object. The component automatically selects the most appropriate unit (seconds through years) and formats the time relative to `baseDate`.

### `date` [#date]

**Type** `Date` · **Optional**

A `Date` to calculate relative time from. When both `date` and `children` are provided, `date` takes precedence.

### `value` [#value]

**Type** `number` · **Optional**

An explicit numeric value for the relative time (for example, `-1` for &quot;yesterday&quot;). Must be used together with `unit`.

### `unit` [#unit]

**Type** `Intl.RelativeTimeFormatUnit` · **Optional**

The unit of time, such as `'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'`, or `'year'`. Required when using `value`.

### `baseDate` [#base-date]

**Type** `Date` · **Optional** · **Default** `new Date()`

The base date relative time is measured against. Defaults to `new Date()` at render time. Set it explicitly to avoid hydration errors — see [below](#hydration).

### `options` [#options]

**Type** `Intl.RelativeTimeFormatOptions` · **Optional** · **Default** `{ numeric: 'auto', style: 'long' }`

The prop uses [`Intl.RelativeTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options). `<RelativeTime>` currently reads these options:

| Option          | Description                                                                                             | Type                            | Optional | Default      |
| --------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------- | -------- | ------------ |
| `localeMatcher` | Locale matching algorithm.                                                                              | `'lookup' \| 'best fit'`        | Yes      | `'best fit'` |
| `style`         | Width of the relative-time wording.                                                                     | `'long' \| 'short' \| 'narrow'` | Yes      | `'long'`     |
| `numeric`       | Whether to always use a number or allow wording such as &quot;yesterday&quot; and &quot;tomorrow&quot;. | `'always' \| 'auto'`            | Yes      | `'auto'`     |

Other fields from the broader `Intl.RelativeTimeFormatOptions` TypeScript type are not forwarded by `<RelativeTime>`.

See the [`Intl.RelativeTimeFormat` options documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options) for the latest standard options. Check the table above for the options currently supported by `<RelativeTime>`.

### `locales` [#locales]

**Type** `string[]` · **Optional** · **Default** Active locale

Locales to format for. If omitted, the active locale is used. See the [locales argument](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).

### `name` [#name]

**Type** `string` · **Optional**

An optional name for the entry, used for metadata.

## Examples [#examples]

*Examples import from `gt-react`; import from your framework&#39;s package instead.*

```tsx title="PostTimestamp.tsx"
import { RelativeTime } from 'gt-react';

export default function PostTimestamp({ post }) {
  return <RelativeTime>{post.createdAt}</RelativeTime>; // [!code highlight]
  // Output: "2 hours ago", "3 days ago", "in 5 minutes", etc.
}
```

```tsx title="PostTimestamp.tsx"
import { RelativeTime } from 'gt-react';

export default function PostTimestamp({ post }) {
  return <RelativeTime date={post.createdAt} />; // [!code highlight]
}
```

```tsx title="Reminder.tsx"
import { RelativeTime } from 'gt-react';

export default function Reminder() {
  return (
    <p>
      Your trial ends <RelativeTime value={3} unit="day" />. // [!code highlight]
    </p>
  );
  // Output: "Your trial ends in 3 days."
}
```

```tsx title="Comment.tsx"
import { T, RelativeTime } from 'gt-react';

export default function Comment({ comment }) {
  return (
    <T>
      Posted <RelativeTime>{comment.createdAt}</RelativeTime> // [!code highlight]
    </T>
  );
}
```

```tsx title="NumericTimestamp.tsx"
import { RelativeTime } from 'gt-react';

export default function NumericTimestamp({ date }) {
  return (
    <RelativeTime
      options={{
        numeric: 'always', // [!code highlight]
        style: 'narrow', // [!code highlight]
      }}
    >
      {date}
    </RelativeTime>
  );
  // With numeric: 'always', outputs "1 day ago" instead of "yesterday"
}
```

## Avoiding hydration errors [#hydration]

Because `<RelativeTime>` computes relative time locally, it can produce different output on the server and the client, causing a hydration error. This typically happens when:

* **`baseDate` defaults to `new Date()` at render time.** The server and client render at slightly different moments. If the relative time crosses a unit boundary between them (for example, &quot;59 seconds ago&quot; → &quot;1 minute ago&quot;), the output will not match.
* **The default locale differs between environments**, producing different strings (for example, &quot;hace 2 horas&quot; vs. &quot;2 hours ago&quot;).

Pin both the locale and a shared `baseDate` so the server and client always produce the same string:

```tsx
const now = new Date(); // computed once, passed to both server and client

<RelativeTime locales={['en-US']} baseDate={now}>
  {post.createdAt}
</RelativeTime>
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.