# General Translation Platform: formatRelativeTimeFromDate
URL: https://generaltranslation.com/en-GB/docs/platform/core/reference/utility-functions/formatting/format-relative-time-from-date.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Format relative time from a date without a GT instance. API reference for formatRelativeTimeFromDate.

[`formatRelativeTimeFromDate`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time-from-date) is a standalone utility function from General Translation's Core library that formats a relative time string given a `Date`, automatically selecting the most appropriate unit (seconds, minutes, hours, days, weeks, months, or years).

## Overview [#overview]

Import `formatRelativeTimeFromDate` directly from `generaltranslation` and call it with a `Date` and an options object. It does not require an API key or a [GT](/docs/platform/core/reference/gt-class/constructor) instance. For instance-based formatting that inherits the instance locale, use the [`formatRelativeTimeFromDate`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time-from-date) method on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance instead. To format an explicit value and unit yourself, use [`formatRelativeTime`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time).

```typescript
import { formatRelativeTimeFromDate } from 'generaltranslation';

const pastDate = new Date(Date.now() - 7200000); // 2 hours ago
const formatted = formatRelativeTimeFromDate(pastDate, {
  locales: 'en-US',
  baseDate: new Date(),
});
// Returns: "2 hours ago"
```

Signature:

```typescript
formatRelativeTimeFromDate(
  date: Date,
  options?: { locales?: string | string[] }
    & Omit<Intl.RelativeTimeFormatOptions, 'locales'>
    & { baseDate?: Date }
): string
```

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

* **Unit selection.** Automatically selects the most appropriate unit based on the difference between `date` and `baseDate`.
* **Underlying API.** Uses [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) under the hood.
* **Numeric mode.** Defaults to `numeric: 'auto'` and `style: 'long'`.
* **Base date default.** When `baseDate` is not provided, it defaults to `new Date()`. Be aware that this can cause hydration mismatches in server-rendered apps.
* **Locale resolution.** When `locales` is omitted, it falls back to the library default locale, `en`.

## Parameters [#parameters]

| Parameter             | Description                                                                            | Type                                                                                                       | Optional | Default |
| --------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------- | ------- |
| [`date`](#date)       | The date to format relative to `baseDate`.                                             | `Date`                                                                                                     | No       | —       |
| [`options`](#options) | Formatting configuration, including the target locale(s) and the comparison base date. | `{ locales?: string \| string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'> & { baseDate?: Date }` | Yes      | `{}`    |

### `date` [#date]

**Type** `Date` · **Required**

The `Date` to format relative to `baseDate`.

### `options` [#options]

**Type** `{ locales?: string | string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'> & { baseDate?: Date }` · **Optional** · **Default** `{}`

Formatting configuration. The table lists `baseDate`, `locales`, and common options exposed by the published Core types, with their effective Core defaults. (See the [`Intl.RelativeTimeFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options) for supplementary standard and runtime-specific details).

| Property        | Description                           | Type                            | Optional | Default      |
| --------------- | ------------------------------------- | ------------------------------- | -------- | ------------ |
| `locales`       | Locale(s) for formatting.             | `string \| string[]`            | Yes      | `en`         |
| `baseDate`      | The base date for comparison.         | `Date`                          | Yes      | `new Date()` |
| `numeric`       | Whether to always use numeric output. | `'always' \| 'auto'`            | Yes      | `'auto'`     |
| `style`         | The length of the output.             | `'long' \| 'short' \| 'narrow'` | Yes      | `'long'`     |
| `localeMatcher` | The locale matching algorithm to use. | `'best fit' \| 'lookup'`        | Yes      | `'best fit'` |

`baseDate` is a Core-only field and is not passed to `Intl.RelativeTimeFormat`. Core also changes the upstream `numeric` default from `'always'` to `'auto'`.

## Returns [#returns]

**Type** `string`

The formatted relative time string (for example, &quot;2 hours ago&quot;, &quot;in 3 days&quot;).

## Examples [#examples]

```typescript
import { formatRelativeTimeFromDate } from 'generaltranslation';

const now = new Date();

// 2 hours ago
const pastDate = new Date(now.getTime() - 7200000);
console.log(formatRelativeTimeFromDate(pastDate, {
  locales: 'en-US',
  baseDate: now,
}));
// Output: "2 hours ago"

// 3 days in the future
const futureDate = new Date(now.getTime() + 259200000);
console.log(formatRelativeTimeFromDate(futureDate, {
  locales: 'en-US',
  baseDate: now,
}));
// Output: "in 3 days"
```

```typescript
// Multiple locales
const pastDate = new Date(Date.now() - 86400000); // ~1 day ago
const now = new Date();

const locales = ['en-US', 'fr-FR', 'ja-JP', 'de-DE'];

locales.forEach((locale) => {
  console.log(`${locale}: ${formatRelativeTimeFromDate(pastDate, {
    locales: locale,
    baseDate: now,
  })}`);
});
// Output:
// en-US: yesterday
// fr-FR: hier
// ja-JP: 昨日
// de-DE: gestern
```

## Notes [#notes]

* Automatically selects the most appropriate unit based on the difference between `date` and `baseDate`.
* Defaults to `numeric: 'auto'` and `style: 'long'`.
* If `baseDate` is not provided, it defaults to `new Date()` — be aware that this can cause hydration mismatches in server-rendered apps.
* Uses [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) under the hood.

## Sitemap

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