# react-native: RelativeTime
URL: https://generaltranslation.com/en-US/docs/react-native/api/components/relativetime.mdx
---
title: RelativeTime
description: API reference for the RelativeTime component
---
{/* AUTO-GENERATED: Do not edit directly. Edit the template in content/docs-templates/ instead. */}


## Overview

The `<RelativeTime>` component renders a localized relative time string, such as "2 hours ago" or "in 3 days".
It supports two usage modes: automatically selecting the best unit from a `Date`, or explicitly specifying a value and unit.

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

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

<Callout type="warn">
  `<RelativeTime>` can cause **React hydration errors** in server-rendered apps. See [Avoiding hydration errors](#avoiding-hydration-errors) below.
</Callout>

## Reference

### Props

<TypeTable
  type={{
    "children?": {
        description: 'A Date object to compute relative time from.',
        type: 'Date',
        optional: true,
        default: 'undefined',
    },
    "date?": {
        description: 'A Date object to compute relative time from. Takes precedence over children.',
        type: 'Date',
        optional: true,
        default: 'undefined',
    },
    "value?": {
        description: 'Explicit numeric value for relative time. Requires unit.',
        type: 'number',
        optional: true,
        default: 'undefined',
    },
    "unit?": {
        description: 'The unit of time. Required when using value.',
        type: 'Intl.RelativeTimeFormatUnit',
        optional: true,
        default: 'undefined',
    },
    "baseDate?": {
        description: 'Base date for computing relative time. Defaults to new Date() at render time.',
        type: 'Date',
        optional: true,
        default: 'new Date()',
    },
    "name?": {
        type: 'string',
        optional: true,
        default: 'undefined',
    },
    "options?": {
        type: 'Intl.RelativeTimeFormatOptions',
        optional: true,
        default: "{ numeric: 'auto', style: 'long' }",
    },
    "locales?": {
        type: 'string[]',
        optional: true,
        default: 'undefined',
    },
  }}
/>

### Description
| Prop Name | Description |
|-----------|-------------|
| `children` | A `Date` object. The component automatically selects the best unit (seconds, minutes, hours, days, weeks, months, or years) and formats the time relative to `baseDate`. |
| `date` | A `Date` object to compute relative time from. If both `date` and `children` are provided, `date` takes precedence. |
| `value` | An explicit numeric value for the relative time (e.g., `-1` for "yesterday"). Must be used together with `unit`. |
| `unit` | The unit of time (e.g., `'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'`, `'year'`). Required when using `value`. |
| `baseDate` | The base date for computing relative time. Defaults to `new Date()` at render time. **Set this explicitly to avoid hydration errors** — see [below](#avoiding-hydration-errors). |
| `options` | Optional formatting options following the [`Intl.RelativeTimeFormatOptions` specification](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat). Defaults to `numeric: 'auto'` and `style: 'long'`. |
| `locales` | Optional locales to specify the formatting locale. If not provided, the user's locale is used. Read more about specifying locales [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument). |

### Returns

`JSX.Element` containing the formatted relative time as a string, or `null` if no date or value is provided.

---
## Examples

### Auto-select unit from a Date
Pass a `Date` as children and the component automatically picks the best unit.

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

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

### Using the date prop
You can also pass the date via the `date` prop instead of `children`.

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

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

### Explicit value and unit
Specify an exact value and unit, mirroring the `Intl.RelativeTimeFormat` API.

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

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

### Specifying locales
Display relative time in a specific locale.

```jsx title="FrenchTimestamp.jsx" copy
import { RelativeTime } from 'gt-react-native';

export default function FrenchTimestamp({ date }) {
    return (
        <RelativeTime locales={['fr-FR']}>{date}</RelativeTime> // [!code highlight]
    );
    // Output: "il y a 2 heures"
}
```

### Translating RelativeTime
Wrap `<RelativeTime>` in a `<T>` component to include it in a translated sentence.

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

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

### Custom formatting options
Control the output style with `Intl.RelativeTimeFormat` options.

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

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

Because `<RelativeTime>` computes relative time locally, it can produce **different output on the server and client**. When React compares the server-rendered HTML to the client render and they don't match, you get a hydration error.

This typically happens when:

- **`baseDate` defaults to `new Date()` at render time.** The server renders at one moment, then the client hydrates seconds (or more) later. If the relative time crosses a unit boundary between those two moments (e.g., "59 seconds ago" → "1 minute ago"), the output won't match.
- **The default locale differs between environments.** If the server's default locale doesn't match the client's, the formatted string may differ (e.g., "hace 2 horas" vs "2 hours ago").

### How to fix it

**Set an explicit `baseDate`** to ensure the server and client compute the same relative time:

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

<RelativeTime baseDate={now}>{post.createdAt}</RelativeTime>
```

**Specify explicit `locales`** to avoid locale mismatches:

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

By pinning both the locale and base date, the server and client will always produce the same formatted string.

## Notes
 * The `<RelativeTime>` component is a variable component that formats relative time values.
 * When using auto mode (with a `Date`), the component selects the most appropriate unit automatically.
 * The component uses [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) under the hood.
 * Default formatting options are `numeric: 'auto'` and `style: 'long'`.

## Next steps
 * For more details and usage examples of the `<RelativeTime>` component and other variable components like `<DateTime>`, `<Currency>`, `<Num>`, and `<Var>`, see the [Using Variable Components](/docs/react-native/guides/variables) documentation.