---
url: https://react-ui.bas.dev/formatting/dates.md
---
# Dates and times

Clocks, days and moments, each in the region's order and clock with the words of the language.

```ts
import { formatClock, formatDay, formatDayClock, formatMoment } from '@basmilius/react-ui/format';
```

Every function takes a `Date` or epoch milliseconds.

| Function | Writes |
| --- | --- |
| `formatClock(at)` | The time: `08:05`, or `08:05 AM` in a region that counts to twelve. |
| `formatHour(at)` | An hour on its own, for the axis of a chart: `08`, or `8 AM`. |
| `formatWeekdayClock(at)` | A time far enough off that its day is part of the answer: `Sat 08:05`. |
| `formatDay(at)` | The short date a row falls back to once "days ago" stops meaning anything: `19 Sep`. |
| `formatDayWithYear(at)` | The same with the year, for anything older than this year. |
| `formatWeekdayDay(at)` | `Sat 19 Sep`. |
| `formatDayClock(at)` | A moment that is not today, to the minute: `19 Sep, 08:05`. |
| `formatNumericDate(at)` | All numbers, as a form prints it: `19-9-2026` or `9/19/2026`. |
| `formatMoment(at, now?)` | The clock when `at` is today, and the day and the clock when it is not. |
| `formatDateTime(at, options)` | Any `Intl.DateTimeFormatOptions`, with the same split between words and notation. |
| `isSameDay(a, b)` | Whether two instants fall on the same day, in the reader's time zone. |

## How the words get in

`formatDateTime` formats the instant twice with the same options: once in the region, for the order and the numbers, and once in the language, for the words. It then puts the language's month, weekday, day period and era into the region's layout. The region decides where the month goes; the language decides what it is called.

Use `formatDateTime` for a format none of the others writes, and define its options object once, outside the component. The formatter is cached on that object, so a fresh object per call builds a fresh formatter.