@dnb/eufemia/docs/uilib/components/date-format.md

DNB Eufemia Design System UI Library

---
title: 'DateFormat'
description: 'A ready to use DNB date formatter.'
version: 10.104.0
generatedAt: 2026-04-17T18:46:09.728Z
checksum: bb2fb35cc775a9c00003a92f666a842814da9015d5117bfdcc1637684fd1f961
---

# DateFormat

## Import

```tsx
import { DateFormat } from '@dnb/eufemia'
```

## Description

A ready to use DNB date formatter. Use it wherever you want to format dates.

Good reasons to use this component:

- Makes the date formatting uniform for all DNB applications.
- Makes dates accessible to screen readers.

For a quick overview of all supported date and number formats per locale, see [Best Practices for number formatting](/uilib/usage/best-practices/for-formatting/).

Good to know:

- You can render a date in **different formats**, depending on the locale.
- The component supports **relative time**, such as "2 hours ago", "in 3 days", etc.
- The component supports different **date styles**, such as `short`, `medium`, `long`, and `full`.
- You can include **time** by using the `timeStyle` prop.
- Use `relativeTimeStyle` to control the style used for relative time.
- The component will automatically detect and format **ISO 8601 duration** strings.

## Relevant links

- [Source code](https://github.com/dnbexperience/eufemia/tree/main/packages/dnb-eufemia/src/components/date-format)
- [Docs code](https://github.com/dnbexperience/eufemia/tree/main/packages/dnb-design-system-portal/src/docs/uilib/components/date-format)

### Under the hood

The component uses `Intl.DateTimeFormat` browser API and `Date.toLocaleDateString` as a fallback, to format dates based on locale.

See [Intl.DateTimeFormat locale documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument) for accepted string formats.

The [time element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/time) is used to ensure that the date is readable for screen readers.

### Supported date value formats

The following formats are supported as date values for conversion:

- `yyyy-MM-dd`
- `dd.MM.yyyy`
- `dd/MM/yyyy`
- `Date` object

### Relative time reference

When using `relativeTime`, you can provide a `now` prop (as a function) to define the reference point for relative time calculations. This is useful for testing or when you need a specific reference time. If not provided, the current time is used.

### `formatDate` helper function

If you really need a formatted date string without rendering the component, you can import the utility directly:

```ts
import { formatDate } from '@dnb/eufemia/components/date-format/DateFormatUtils'
formatDate('2023-01-01', {
  locale: 'en-GB',
  dateStyle: 'long',
})
```

### `getOsloDate` helper

When you need a UTC Date object with midnight that always reflects the current day in `Europe/Oslo`, pull in the helper directly:

```ts
import { getOsloDate } from '@dnb/eufemia/components/date-format/DateFormatUtils'
getOsloDate() // -> e.g. Date object representing "2025-11-24T00:00:00.000Z" regardless of the runtime timezone
```

This is helpful when you are comparing "today" against backend data or applying Oslo-specific highlighting in the [DatePicker](/uilib/components/date-picker/).

#### Parameters

| Name      | Type                         | Default                  | Description                                                                                                                                                       |
| --------- | ---------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `locale`  | `AnyLocale`                  | `'nb-NO'`                | The locale to use for formatting.                                                                                                                                 |
| `options` | `Intl.DateTimeFormatOptions` | `{ dateStyle: 'short' }` | The format options following the [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) API. |

## Demos

<ChangeLocale
  bottom
  label="Locale used in the demos:"
  listUSLocale={true}
/>

### Date styles

```tsx
render(
  <Style>
    <ComponentBox data-visual-test="date-format-date-styles">
      <P>
        <DateFormat dateStyle="full">2025-08-01</DateFormat>
        <DateFormat dateStyle="long">2025-08-01</DateFormat>
        <DateFormat dateStyle="medium">2025-08-01</DateFormat>
        <DateFormat dateStyle="short">2025-08-01</DateFormat>
      </P>
    </ComponentBox>
  </Style>
)
```

### Hide year when in current year

Use `hideCurrentYear` to hide the year when the date is in the
current year. Works with any `dateStyle`.

Use `hideYear` to always hide the year from the formatted date,

```tsx
render(
  <Style>
    <ComponentBox>
      {() => {
        const currentYear = new Date().getFullYear()
        const dateInCurrentYear = `${currentYear}-02-04`
        const dateInOtherYear = `${currentYear - 1}-02-04`
        return (
          <P>
            <DateFormat
              value={dateInCurrentYear}
              dateStyle="medium"
              hideCurrentYear
            />
            <DateFormat
              value={dateInOtherYear}
              dateStyle="medium"
              hideCurrentYear
            />
            <Hr />
            <DateFormat
              value={dateInCurrentYear}
              dateStyle="long"
              hideCurrentYear
            />
            <DateFormat
              value={dateInOtherYear}
              dateStyle="long"
              hideCurrentYear
            />
          </P>
        )
      }}
    </ComponentBox>
  </Style>
)
```

### Inline

```tsx
render(
  <P>
    Payment due <DateFormat>2025-08-01</DateFormat>. Please make sure you
    have sufficient funds available.
  </P>
)
```

### Date value formats

```tsx
render(
  <Style>
    <ComponentBox>
      <P>
        <DateFormat>2025-08-01</DateFormat>
        <DateFormat>01.08.2025</DateFormat>
        <DateFormat>01/08/2025</DateFormat>
        <DateFormat value={new Date('2025-08-01')} />
      </P>
    </ComponentBox>
  </Style>
)
```

### Date and time

Use the `timeStyle` property to include a time value alongside the date. Add
`dateTimeSeparator` if you need a custom separator.

```tsx
render(
  <P>
    Updated at{' '}
    <DateFormat
      value={new Date('2026-01-13T11:55:00')}
      dateStyle="medium"
      timeStyle="short"
      dateTimeSeparator=" – "
    />
  </P>
)
```

### Relative time

```tsx
render(
  <Style>
    <ComponentBox>
      <P>
        <DateFormat
          value={new Date(new Date().getTime() - 30 * 1000)}
          relativeTime
        />
        <DateFormat
          value={new Date(new Date().getTime() - 2 * 60 * 1000)}
          relativeTime
        />
        <DateFormat
          value={new Date(new Date().getTime() - 24 * 60 * 60 * 1000)}
          relativeTime
        />
      </P>
    </ComponentBox>
  </Style>
)
```

### Relative time with different styles

Use `relativeTimeStyle` to control the relative time formatting without affecting `dateStyle`.

```tsx
render(
  <Style>
    <ComponentBox
      scope={{
        pastDates,
        futureDates,
      }}
      hideCode
    >
      <H4>Short:</H4>
      {pastDates.map((date, index) => (
        <P key={index}>
          <DateFormat
            value={date}
            relativeTime
            relativeTimeStyle="short"
          />
          {index < pastDates.length - 1 && <br />}
        </P>
      ))}

      <H4>Medium:</H4>
      {pastDates.map((date, index) => (
        <P key={index}>
          <DateFormat
            value={date}
            relativeTime
            relativeTimeStyle="medium"
          />
          {index < pastDates.length - 1 && <br />}
        </P>
      ))}

      <H4>Long (default):</H4>
      {pastDates.map((date, index) => (
        <P key={index}>
          <DateFormat value={date} relativeTime relativeTimeStyle="long" />
          {index < pastDates.length - 1 && <br />}
        </P>
      ))}

      <H4>Future dates with long style:</H4>
      {futureDates.map((date, index) => (
        <P key={index}>
          <DateFormat value={date} relativeTime relativeTimeStyle="long" />
          {index < futureDates.length - 1 && <br />}
        </P>
      ))}

      <H4>Different locales with short style:</H4>
      <P>
        <DateFormat
          value={pastDates[2]}
          relativeTime
          relativeTimeStyle="short"
          locale="de-DE"
        />
        <DateFormat
          value={futureDates[2]}
          relativeTime
          relativeTimeStyle="short"
          locale="sv-SE"
        />
      </P>
    </ComponentBox>
  </Style>
)
```

### Duration formatting

The DateFormat component automatically detects and formats ISO
8601 duration strings. No additional properties are needed.

- `PT1H` = 1 hour (P = period, T = time, 1H = 1 hour)
- `PT2H30M` = 2 hours 30 minutes
- `P1D` = 1 day (P = period, 1D = 1 day)
- `P1DT2H30M` = 1 day 2 hours 30 minutes
- `P1W` = 1 week,
- `P1M` = 1 month
- `P1Y` = 1 year

```tsx
render(
  <Style>
    <ComponentBox>
      <H4>Short durations:</H4>
      <P>
        <DateFormat value="PT1H" />
        <DateFormat value="PT2H30M" />
        <DateFormat value="PT45M" />
      </P>

      <H4>Longer durations:</H4>
      <P>
        <DateFormat value="P1D" />
        <DateFormat value="P1DT2H30M" />
        <DateFormat value="P1W" />
        <DateFormat value="P1M" />
        <DateFormat value="P1Y" />
      </P>

      <H4>Different locales:</H4>
      <P>
        <DateFormat value="PT2H30M" locale="en-US" />
        <DateFormat value="PT2H30M" locale="nb-NO" />
        <DateFormat value="PT2H30M" locale="de-DE" />
      </P>
    </ComponentBox>
  </Style>
)
```

### Duration with different styles

The `dateStyle` property affects how durations are formatted using the browser's built-in `Intl.DurationFormat` API.

```tsx
render(
  <Style>
    <ComponentBox>
      <H4>Short:</H4>
      <P>
        <DateFormat value="PT2H30M" dateStyle="short" />
        <DateFormat value="P1DT2H30M" dateStyle="short" />
      </P>

      <H4>Medium:</H4>
      <P>
        <DateFormat value="PT2H30M" dateStyle="medium" />
        <DateFormat value="P1DT2H30M" dateStyle="medium" />
      </P>

      <H4>Long (default):</H4>
      <P>
        <DateFormat value="PT2H30M" dateStyle="long" />
        <DateFormat value="P1DT2H30M" dateStyle="long" />
      </P>

      <H4>Different locales with short style:</H4>
      <P>
        <DateFormat value="PT2H30M" dateStyle="short" locale="en-US" />
        <DateFormat value="PT2H30M" dateStyle="short" locale="nb-NO" />
        <DateFormat value="PT2H30M" dateStyle="short" locale="de-DE" />
      </P>
    </ComponentBox>
  </Style>
)
```

## Properties

```json
{
  "props": {
    "value": {
      "doc": "The date that will be formatted.",
      "type": ["Date", "string"],
      "status": "optional"
    },
    "dateStyle": {
      "doc": "Defines the style used to format the date. Also affects duration formatting when using ISO 8601 duration strings. Defaults to `long`.",
      "type": ["long", "medium", "short", "full"],
      "status": "optional"
    },
    "hideCurrentYear": {
      "doc": "When `true`, the year is hidden if the date is in the current year, for any `dateStyle` (e.g. \"4. feb.\" instead of \"4. feb. 2025\"). Defaults to `false`.",
      "type": "boolean",
      "status": "optional"
    },
    "hideYear": {
      "doc": "When `true`, the year is always hidden from the formatted date, for any `dateStyle`. Defaults to `false`.",
      "type": "boolean",
      "status": "optional"
    },
    "timeStyle": {
      "doc": "Defines the style used to format the time. If provided, time is included in the output.",
      "type": ["long", "medium", "short", "full"],
      "status": "optional"
    },
    "dateTimeSeparator": {
      "doc": "Custom separator used between date and time when both are rendered (e.g. \" - \"). When not provided, uses the locale-appropriate separator (e.g. \" kl. \" for Norwegian, \" at \" for English).",
      "type": "string",
      "status": "optional"
    },
    "relativeTime": {
      "doc": "If set to `true`, actual dates will be formatted as relative time (e.g., \"2 hours ago\"). ISO 8601 duration strings (e.g., \"PT1H\") are automatically detected and formatted without this prop. Defaults to `false`.",
      "type": "boolean",
      "status": "optional"
    },
    "relativeTimeStyle": {
      "doc": "Defines the style used to format relative time. Defaults to `dateStyle` when not provided.",
      "type": ["long", "medium", "short", "full"],
      "status": "optional"
    },
    "relativeTimeReference": {
      "doc": "A function that returns a Date object to use as the reference point for relative time calculations. If not provided, the current time is used.",
      "type": "function",
      "status": "optional"
    },
    "locale": {
      "doc": "A string in [Intl.DateTimeFormat locale](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument) format. Duration formatting supports all locales using the browser's built-in internationalization. Defaults to `nb-NO`.",
      "type": "string",
      "status": "optional"
    },
    "skeleton": {
      "doc": "If set to `true`, an overlaying skeleton with animation will be shown.",
      "type": "boolean",
      "status": "optional"
    },
    "[Space](/uilib/layout/space/properties)": {
      "doc": "Spacing properties like `top` or `bottom` are supported.",
      "type": ["string", "object"],
      "status": "optional"
    }
  }
}
```