# generaltranslation: General Translation Core SDK: formatRelativeTime
URL: https://generaltranslation.com/en-US/docs/core/class/methods/formatting/format-relative-time.mdx
---
title: formatRelativeTime
description: API reference for the formatRelativeTime method to format relative time values
---

## Overview

The `formatRelativeTime` method formats a relative time value with an explicit unit, according to locale-specific conventions.

```typescript
const gt = new GT();
const formatted = gt.formatRelativeTime(-1, 'day', {
  locales: 'en-US',
  numeric: 'auto'
});
// Returns: "yesterday"
```

## Reference

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `value` | `number` | The relative time value (negative for past, positive for future) |
| `unit` | `Intl.RelativeTimeFormatUnit` | The unit of time (`'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'`, `'year'`) |
| `options?` | `object` | Formatting configuration |

### Options

| Name | Type | Description |
|------|------|-------------|
| `locales?` | `string \| string[]` | Locales for formatting. Falls back to the instance's rendering locales |
| `numeric?` | `'always' \| 'auto'` | Whether to always use numeric output. Defaults to `'auto'` |
| `style?` | `'long' \| 'short' \| 'narrow'` | The length of the output. Defaults to `'long'` |
| `localeMatcher?` | `'best fit' \| 'lookup'` | The locale matching algorithm to use |

### Returns

`string` - The formatted relative time string.

---

## Example

```typescript copy
import GT from 'generaltranslation';
const gt = new GT();

// Past time
gt.formatRelativeTime(-2, 'hour', { locales: 'en-US' });
// Returns: "2 hours ago"

// Future time
gt.formatRelativeTime(3, 'day', { locales: 'fr-FR' });
// Returns: "dans 3 jours"

// With numeric: 'auto' (default)
gt.formatRelativeTime(-1, 'day', { locales: 'en-US' });
// Returns: "yesterday"
```

---

## Notes

* Defaults to `numeric: 'auto'` and `style: 'long'`
* Uses [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) under the hood

## Next steps

* See [`formatRelativeTimeFromDate`](/docs/core/class/methods/formatting/format-relative-time-from-date) for auto-selecting the unit from a Date
* See the standalone [`formatRelativeTime`](/docs/core/functions/formatting/format-relative-time) function for usage without a GT instance