# General Translation Platform: formatRelativeTimeFromDate
URL: https://generaltranslation.com/en-GB/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time-from-date.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Format relative time from a date compared with the current time or another date. API reference for formatRelativeTimeFromDate.

Formats a relative time string from a `Date`, automatically selecting the most appropriate unit, on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. General Translation compares the date against a base date (the current time by default) and produces phrases such as "2 hours ago" or "in 3 days".

## Overview [#overview]

Call `formatRelativeTimeFromDate` on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance with the target `Date` and an optional options object. It returns the formatted string, choosing the unit that best fits the time difference.

```typescript
const gt = new GT();
const pastDate = new Date(Date.now() - 7200000); // 2 hours ago

const formatted = gt.formatRelativeTimeFromDate(pastDate, {
  locales: 'en-US',
});
// "2 hours ago"
```

Signature:

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

*Note: `formatRelativeTimeFromDate` runs locally using `Intl.RelativeTimeFormat` and does not require an API key. It uses the instance&#39;s target locale by default, then falls back to the source locale and `en`. For formatting without a `GT` instance, see the standalone [`formatRelativeTimeFromDate`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time-from-date).*

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

* **Automatic unit selection.** The method calculates the difference between `date` and `baseDate` and picks the most appropriate unit (seconds, minutes, hours, days, and so on).
* **Base date.** Comparison is against `baseDate`, which defaults to `new Date()` (the current time).
* **Locale resolution.** When `locales` is omitted, the method uses the instance&#39;s target locale, then the source locale and `en`.
* **Defaults.** `numeric` defaults to `'auto'` and `style` defaults to `'long'`.

## Parameters [#parameters]

| Parameter             | Description                                | Type     | Optional | Default |
| --------------------- | ------------------------------------------ | -------- | -------- | ------- |
| [`date`](#date)       | The date to format relative to `baseDate`. | `Date`   | No       | —       |
| [`options`](#options) | Formatting configuration.                  | `object` | Yes      | —       |

### `date` [#date]

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

The date to format relative to `baseDate`.

### `options` [#options]

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

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 additional standard and runtime-specific details).

| Name            | Description                           | Type                            | Optional | Default                                |
| --------------- | ------------------------------------- | ------------------------------- | -------- | -------------------------------------- |
| `locales`       | Locales for formatting.               | `string \| string[]`            | Yes      | `targetLocale` → `sourceLocale` → `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, such as &quot;2 hours ago&quot; or &quot;in 3 days&quot;.

## Examples [#examples]

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

const gt = new GT();

const now = new Date();

// Auto-selects "hours"
const twoHoursAgo = new Date(now.getTime() - 7200000);
gt.formatRelativeTimeFromDate(twoHoursAgo, { locales: 'en-US', baseDate: now });
// Returns: "2 hours ago"

// Auto-selects "days"
const threeDaysLater = new Date(now.getTime() + 259200000);
gt.formatRelativeTimeFromDate(threeDaysLater, { locales: 'fr-FR', baseDate: now });
// Returns: "dans 3 jours"
```

## Notes [#notes]

* Automatically selects the most appropriate unit based on the time difference.
* Defaults to `numeric: 'auto'` and `style: 'long'`.
* If `baseDate` is not provided, it defaults to `new Date()`.
* For explicit value + unit formatting, use [`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time).

## Sitemap

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