0
# Date and Time Formatting
1

2
Locale-aware date and time formatting with calendar support, timezone handling, and automatic locale updates.
3

4
## Capabilities
5

6
### useDateFormatter Hook
7

8
Provides localized date formatting for the current locale with automatic caching and locale updates.
9

10
```typescript { .api }
11
/**
12
 * Provides localized date formatting for the current locale. Automatically updates when the locale changes,
13
 * and handles caching of the date formatter for performance.
14
 * @param options - Formatting options extending Intl.DateTimeFormatOptions
15
 * @returns DateFormatter instance from @internationalized/date
16
 */
17
function useDateFormatter(options?: DateFormatterOptions): DateFormatter;
18

19
interface DateFormatterOptions extends Intl.DateTimeFormatOptions {
20
  /** Calendar system to use (e.g., 'gregory', 'buddhist', 'islamic') */
21
  calendar?: string;
22
}
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { useDateFormatter, I18nProvider } from "@react-aria/i18n";
29

30
// Basic date formatting
31
function DateDisplay() {
32
  const formatter = useDateFormatter({ 
33
    dateStyle: "long" 
34
  });
35
  
36
  return <p>{formatter.format(new Date())}</p>;
37
  // US English: "December 25, 2023"
38
  // Spanish: "25 de diciembre de 2023"
39
}
40

41
// Time formatting with specific options
42
function TimeDisplay() {
43
  const formatter = useDateFormatter({
44
    timeStyle: "medium",
45
    hour12: false
46
  });
47
  
48
  return <p>{formatter.format(new Date())}</p>;
49
  // "14:30:00"
50
}
51

52
// Custom format with multiple fields
53
function CustomDateFormat() {
54
  const formatter = useDateFormatter({
55
    weekday: "long",
56
    year: "numeric",
57
    month: "long",
58
    day: "numeric"
59
  });
60
  
61
  return <p>{formatter.format(new Date())}</p>;
62
  // "Monday, December 25, 2023"
63
}
64

65
// Calendar-specific formatting
66
function BuddhistCalendarDate() {
67
  const formatter = useDateFormatter({
68
    calendar: "buddhist",
69
    dateStyle: "full"
70
  });
71
  
72
  return <p>{formatter.format(new Date())}</p>;
73
  // Uses Buddhist calendar era
74
}
75

76
// Responsive to locale changes
77
function LocaleAwareDateDisplay() {
78
  return (
79
    <div>
80
      <I18nProvider locale="en-US">
81
        <DateDisplay />
82
      </I18nProvider>
83
      <I18nProvider locale="ja-JP">
84
        <DateDisplay />
85
      </I18nProvider>
86
    </div>
87
  );
88
}
89
```
90

91
### DateFormatter Methods
92

93
The DateFormatter instance provides additional methods beyond basic formatting.
94

95
```typescript { .api }
96
interface DateFormatter {
97
  /** Format a date to a string */
98
  format(date: Date): string;
99
  /** Format a date to an array of parts with type information */
100
  formatToParts(date: Date): Intl.DateTimeFormatPart[];
101
  /** Format a date range between two dates */
102
  formatRange(startDate: Date, endDate: Date): string;
103
  /** Format a date range to parts */
104
  formatRangeToParts(startDate: Date, endDate: Date): Intl.DateTimeFormatPart[];
105
  /** Get resolved formatting options */
106
  resolvedOptions(): Intl.ResolvedDateTimeFormatOptions;
107
}
108
```
109

110
**Advanced Usage Examples:**
111

112
```typescript
113
function AdvancedDateFormatting() {
114
  const formatter = useDateFormatter({
115
    year: "numeric",
116
    month: "long",
117
    day: "numeric"
118
  });
119
  
120
  const date = new Date();
121
  const startDate = new Date();
122
  const endDate = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000); // 7 days later
123
  
124
  return (
125
    <div>
126
      {/* Basic formatting */}
127
      <p>Date: {formatter.format(date)}</p>
128
      
129
      {/* Parts formatting for custom styling */}
130
      <p>
131
        Parts: {formatter.formatToParts(date).map((part, i) => (
132
          <span key={i} className={`date-${part.type}`}>
133
            {part.value}
134
          </span>
135
        ))}
136
      </p>
137
      
138
      {/* Date range formatting */}
139
      <p>Range: {formatter.formatRange(startDate, endDate)}</p>
140
      
141
      {/* Resolved options inspection */}
142
      <p>Locale: {formatter.resolvedOptions().locale}</p>
143
    </div>
144
  );
145
}
146
```
147

148
### Calendar System Support
149

150
Support for various calendar systems beyond the Gregorian calendar.
151

152
**Supported Calendar Systems:**
153

154
- `gregory` - Gregorian calendar (default)
155
- `buddhist` - Buddhist calendar  
156
- `chinese` - Chinese calendar
157
- `coptic` - Coptic calendar
158
- `dangi` - Korean Dangi calendar
159
- `ethioaa` - Ethiopian calendar
160
- `ethiopic` - Ethiopian calendar (Amete Alem)
161
- `hebrew` - Hebrew calendar
162
- `indian` - Indian national calendar
163
- `islamic` - Islamic calendar
164
- `islamic-umalqura` - Islamic Umm al-Qura calendar
165
- `islamic-tbla` - Islamic tabular calendar
166
- `islamic-civil` - Islamic civil calendar
167
- `islamic-rgsa` - Islamic calendar (Saudi Arabia)
168
- `iso8601` - ISO 8601 calendar
169
- `japanese` - Japanese calendar
170
- `persian` - Persian calendar
171
- `roc` - Republic of China calendar
172

173
```typescript
174
// Examples with different calendar systems
175
function MultiCalendarDisplay() {
176
  const gregorianFormatter = useDateFormatter({
177
    calendar: "gregory",
178
    dateStyle: "long"
179
  });
180
  
181
  const islamicFormatter = useDateFormatter({
182
    calendar: "islamic",
183
    dateStyle: "long"
184
  });
185
  
186
  const buddhistFormatter = useDateFormatter({
187
    calendar: "buddhist", 
188
    dateStyle: "long"
189
  });
190
  
191
  const date = new Date();
192
  
193
  return (
194
    <div>
195
      <p>Gregorian: {gregorianFormatter.format(date)}</p>
196
      <p>Islamic: {islamicFormatter.format(date)}</p>  
197
      <p>Buddhist: {buddhistFormatter.format(date)}</p>
198
    </div>
199
  );
200
}
201
```