DateFormat
With <DateFormat> helper, you can easily ensure consistent and accurate display of date and time values taking into account factors such as date formats, time formats, time zones, and locale-specific conventions. It provides a way to format and localize dates and times based on the user's preferred language and region.
The <DateFormat> component are built on top of the Intl.DateTimeFormat APIs which provide a comprehensive support for formatting dates based on locale-specific conventions.
Usage
Use <DateFormat> when you want to display date and time values in a way that automatically adapts to the user's locale and language preferences. It is especially useful for presenting read-only dates in UI components such as tables, cards, and labels, ensuring consistency and clarity across different regions.
There is no need to use <DateFormat> with input components like DateField or DatePicker, as they already include their own built-in date formatting and parsing behavior.
Customization options
You can customize how dates and times are displayed by passing any Intl.DateTimeFormat options directly as props to <DateFormat>. This includes settings like date style, time style, time zone, and calendar type.
You can mix and match these options to match your needs. For a full list of available options, see the Intl.DateTimeFormat documentation.
Formatting ranges
The <DateFormat> component can also format a pair of dates as a localized range. By passing an array of two dates to the value prop, you can automatically display them with the correct range separator and formatting for the current locale.
For accessibility, screen readers will treat the formatted range as one continuous string (for example, “Jan 1, 2025 – Dec 31, 2025”). This works well in most cases, but if your interface needs to convey the start and end dates as distinct pieces of information, you can render them as two separate <DateFormat> components and supply explicit ARIA labels. This ensures that assistive technologies announce each value in context.
<Stack role="group" aria-labelledby="date-range-label">
<span id="date-range-label" className="visually-hidden">
Date range
</span>
<DateFormat value={new Date(2025, 0, 1)} aria-label="Start date" />
<span aria-hidden="true"> – </span>
<DateFormat value={new Date(2025, 11, 31)} aria-label="End date" />
</Stack>Tabular display
Use the tabular prop to align dates in columns or tables. When enabled, each digit has the same width, keeping rows straight. This is ideal for data tables, reports, or any layout where vertical alignment helps. To disable it, set tabular={false}.
| Event | Price | Date |
|---|---|---|
| Conference | €199.00 | Mar 10, 2025 |
| Workshop | €49.00 | Jun 22, 2025 |
| Webinar | €0.00 | Sep 5, 2025 |
| Meetup | €10.00 | Nov 18, 2025 |
Props
calendar?string;
dateStyle?"long" | "short" | "full" | "medium";
day?"numeric" | "2-digit";
dayPeriod?"long" | "short" | "narrow";
era?"long" | "short" | "narrow";
formatMatcher?"best fit" | "basic";
fractionalSecondDigits?2 | 1 | 3;
hour?"numeric" | "2-digit";
hour12?boolean;
hourCycle?"h11" | "h12" | "h23" | "h24";
localeMatcher?"best fit" | "lookup";
minute?"numeric" | "2-digit";
month?"long" | "short" | "narrow" | "numeric" | "2-digit";
numberingSystem?string;
second?"numeric" | "2-digit";
tabular?boolean;
"true"timeStyle?"long" | "short" | "full" | "medium";
timeZone?string;
timeZoneName?"long" | "short" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric";
valueDate | [Date, Date];
weekday?"long" | "short" | "narrow";
year?"numeric" | "2-digit";