> For AI agents: the complete documentation index is available at https://wallarm.github.io/design-system/llms.txt, the full documentation bundle is available at https://wallarm.github.io/design-system/llms-full.txt.

# FormatDateTime

Prints a timestamp the way the house date guide says to: `relative` by default for anything recent, `date` when only the day matters, `datetime` when the exact moment does. Relative stops being relative as a date ages — past roughly five months it prints the day and month, past a year it adds the year — and it always carries the full absolute time, timezone included, in a tooltip.

[Source](https://github.com/wallarm/design-system/tree/main/packages/design-system/src/components/FormatDateTime) · [Storybook](https://wallarm.github.io/design-system/storybook/?path=/docs/data-display-formatdatetime--overview)

```tsx
import { subDays, subHours, subMinutes, subMonths, subSeconds, subYears } from 'date-fns';
import { FormatDateTime } from '@wallarm-org/design-system/FormatDateTime';
import { HStack, VStack } from '@wallarm-org/design-system/Stack';

export const Relative = () => (
  <VStack gap={12} align='start'>
    <HStack gap={16} align='center'>
      <FormatDateTime value={subSeconds(now, 10)} format='relative' />
    </HStack>
    <HStack gap={16} align='center'>
      <FormatDateTime value={subMinutes(now, 12)} format='relative' />
    </HStack>
    <HStack gap={16} align='center'>
      <FormatDateTime value={subHours(now, 3)} format='relative' />
    </HStack>
    <HStack gap={16} align='center'>
      <FormatDateTime value={subHours(now, 30)} format='relative' />
    </HStack>
    <HStack gap={16} align='center'>
      <FormatDateTime value={subDays(now, 5)} format='relative' />
    </HStack>
    <HStack gap={16} align='center'>
      <FormatDateTime value={subDays(now, 21)} format='relative' />
    </HStack>
    <HStack gap={16} align='center'>
      <FormatDateTime value={subMonths(now, 3)} format='relative' />
    </HStack>
    <HStack gap={16} align='center'>
      <FormatDateTime value={subDays(now, 200)} format='relative' />
    </HStack>
    <HStack gap={16} align='center'>
      <FormatDateTime value={subYears(now, 2)} format='relative' />
    </HStack>
  </VStack>
);
```

## Usage

```tsx
import { FormatDateTime } from '@wallarm-org/design-system/FormatDateTime';
import { HStack, VStack } from '@wallarm-org/design-system/Stack';
```

## Examples

### Date format

`format='date'` drops the time — and drops the year too when the date falls in the
current one, which is why only the 2025 row carries it.

```tsx
import { FormatDateTime } from '@wallarm-org/design-system/FormatDateTime';
import { VStack } from '@wallarm-org/design-system/Stack';

export const DateFormat = () => (
  <VStack gap={12} align='start'>
    <FormatDateTime value='2026-01-01T00:00:00' format='date' />
    <FormatDateTime value='2026-02-11T14:32:07' format='date' />
    <FormatDateTime value='2025-06-15T09:00:00' format='date' />
  </VStack>
);
```

### Datetime format

`format='datetime'` shows both, the time in secondary type with its timezone, and no
tooltip: there is nothing left to reveal.

```tsx
import { FormatDateTime } from '@wallarm-org/design-system/FormatDateTime';
import { VStack } from '@wallarm-org/design-system/Stack';

export const DatetimeFormat = () => (
  <VStack gap={12} align='start'>
    <FormatDateTime value='2026-01-01T11:00:00' format='datetime' />
    <FormatDateTime value='2026-02-11T14:32:07' format='datetime' />
    <FormatDateTime value='2025-12-25T23:59:59' format='datetime' />
  </VStack>
);
```

### Datetime layout

`stacked` is the default and the table-cell shape; `inline` puts date and time on one
baseline for a row that cannot grow to two lines.

```tsx
import { FormatDateTime } from '@wallarm-org/design-system/FormatDateTime';
import { HStack, VStack } from '@wallarm-org/design-system/Stack';

export const DatetimeLayout = () => (
  <HStack gap={64} align='start'>
    <VStack gap={12} align='start'>
      <FormatDateTime value='2026-01-01T11:00:00' format='datetime' layout='stacked' />
      <FormatDateTime value='2026-02-11T14:32:07' format='datetime' layout='stacked' />
      <FormatDateTime value='2025-12-25T23:59:59' format='datetime' layout='stacked' />
    </VStack>
    <VStack gap={12} align='start'>
      <FormatDateTime value='2026-01-01T11:00:00' format='datetime' layout='inline' />
      <FormatDateTime value='2026-02-11T14:32:07' format='datetime' layout='inline' />
      <FormatDateTime value='2025-12-25T23:59:59' format='datetime' layout='inline' />
    </VStack>
  </HStack>
);
```

### With description

When, and then who or what — the second line is composed from `Text` rather than being
a prop, so it can say anything the row needs.

```tsx
import { FormatDateTime } from '@wallarm-org/design-system/FormatDateTime';
import { VStack } from '@wallarm-org/design-system/Stack';
import { Text } from '@wallarm-org/design-system/Text';

export const WithDescription = () => (
  <VStack gap={12} align='start'>
    <VStack gap={2}>
      <FormatDateTime value='2026-01-01T00:00:00' format='date' />
      <Text size='sm' color='secondary'>
        Created by admin
      </Text>
    </VStack>
    <VStack gap={2}>
      <FormatDateTime value='2026-02-11T14:32:07' format='date' />
      <Text size='sm' color='secondary'>
        Last modified
      </Text>
    </VStack>
  </VStack>
);
```

### Null value

`null` and `undefined` both come out as an em dash rather than an empty cell, with 'No
data' behind it on hover.

```tsx
import { FormatDateTime } from '@wallarm-org/design-system/FormatDateTime';
import { VStack } from '@wallarm-org/design-system/Stack';

export const NullValue = () => (
  <VStack gap={12} align='start'>
    <FormatDateTime value={null} />
    <FormatDateTime value={undefined} />
  </VStack>
);
```

### Future date

A timestamp five minutes ahead reads `Just now` rather than counting forwards — the
component absorbs clock skew between a browser and a server instead of showing it.

```tsx
import { FormatDateTime } from '@wallarm-org/design-system/FormatDateTime';

export const FutureDate = () => (
  <FormatDateTime value={new Date(Date.now() + 5 * 60 * 1000)} format='relative' />
);
```

### Date order and hour cycle

The component respects the app's date order from `DateFormatProvider`. Day-first (the
default) prints "11 Feb, 2026"; month-first prints "Feb 11, 2026". Both hour cycles
are shown: 24-hour and 12-hour with AM/PM.

```tsx
import { subDays } from 'date-fns';
import { DateFormatProvider } from '@wallarm-org/design-system/DateFormatProvider';
import { FormatDateTime } from '@wallarm-org/design-system/FormatDateTime';
import { VStack } from '@wallarm-org/design-system/Stack';

export const DateOrderAndHourCycle = () => (
  <VStack gap={24} align='start'>
    <VStack gap={12} align='start'>
      <DateFormatProvider order='day-first' hourCycle={24}>
        <VStack gap={8} align='start'>
          <FormatDateTime value='2026-02-11T14:32:07' format='date' />
          <FormatDateTime value='2026-02-11T14:32:07' format='datetime' />
          <FormatDateTime value={subDays(now, 200)} format='relative' />
        </VStack>
      </DateFormatProvider>
    </VStack>
    <VStack gap={12} align='start'>
      <DateFormatProvider order='month-first' hourCycle={12}>
        <VStack gap={8} align='start'>
          <FormatDateTime value='2026-02-11T14:32:07' format='date' />
          <FormatDateTime value='2026-02-11T14:32:07' format='datetime' />
          <FormatDateTime value={subDays(now, 200)} format='relative' />
        </VStack>
      </DateFormatProvider>
    </VStack>
    <VStack gap={12} align='start'>
      <DateFormatProvider order='day-first' hourCycle={12}>
        <VStack gap={8} align='start'>
          <FormatDateTime value='2026-02-11T14:32:07' format='date' />
          <FormatDateTime value='2026-02-11T14:32:07' format='datetime' />
          <FormatDateTime value={subDays(now, 200)} format='relative' />
        </VStack>
      </DateFormatProvider>
    </VStack>
    <VStack gap={12} align='start'>
      <DateFormatProvider order='month-first' hourCycle={24}>
        <VStack gap={8} align='start'>
          <FormatDateTime value='2026-02-11T14:32:07' format='date' />
          <FormatDateTime value='2026-02-11T14:32:07' format='datetime' />
          <FormatDateTime value={subDays(now, 200)} format='relative' />
        </VStack>
      </DateFormatProvider>
    </VStack>
  </VStack>
);
```

## Props

| Prop           | Type                                                 | Default    | Description                                                                                                                          |
| -------------- | ---------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| title          | `string \| undefined`                                |            |                                                                                                                                      |
| defaultChecked | `boolean \| undefined`                               |            |                                                                                                                                      |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |            |                                                                                                                                      |
| autoFocus      | `boolean \| undefined`                               |            |                                                                                                                                      |
| id             | `string \| undefined`                                |            |                                                                                                                                      |
| tabIndex       | `number \| undefined`                                |            |                                                                                                                                      |
| rel            | `string \| undefined`                                |            |                                                                                                                                      |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |            |                                                                                                                                      |
| value \*       | `string \| number \| Date \| null \| undefined`      |            | ISO string, Date object, or Unix timestamp (ms)                                                                                      |
| format         | `FormatDateTimeFormat \| undefined`                  | `relative` | Display format. Default: 'relative'                                                                                                  |
| layout         | `FormatDateTimeLayout \| undefined`                  | `stacked`  | Datetime layout. `stacked` puts date over time; `inline` puts them on one line. Only affects `format='datetime'`. Default: 'stacked' |
| showSeconds    | `boolean \| undefined`                               | `true`     | Show seconds in the relative-format tooltip. Default: true                                                                           |
| data-testid    | `string \| undefined`                                |            |                                                                                                                                      |