0
# Number and List Formatting
1

2
Numeric formatting and list presentation for different locales and cultural contexts with automatic locale updates and performance caching.
3

4
## Capabilities
5

6
### useNumberFormatter Hook
7

8
Provides localized number formatting for the current locale with support for currency, percentages, and custom number styles.
9

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

19
type NumberFormatOptions = Intl.NumberFormatOptions;
20
```
21

22
**Usage Examples:**
23

24
```typescript
25
import { useNumberFormatter, I18nProvider } from "@react-aria/i18n";
26

27
// Basic number formatting
28
function NumberDisplay() {
29
  const formatter = useNumberFormatter();
30
  
31
  return <p>{formatter.format(1234567.89)}</p>;
32
  // US English: "1,234,567.89"
33
  // German: "1.234.567,89"
34
  // French: "1 234 567,89"
35
}
36

37
// Currency formatting
38
function CurrencyDisplay() {
39
  const formatter = useNumberFormatter({
40
    style: "currency",
41
    currency: "USD"
42
  });
43
  
44
  return <p>{formatter.format(1299.99)}</p>;
45
  // US English: "$1,299.99"
46
  // UK English: "US$1,299.99"
47
}
48

49
// Percentage formatting
50
function PercentageDisplay() {
51
  const formatter = useNumberFormatter({
52
    style: "percent",
53
    minimumFractionDigits: 1
54
  });
55
  
56
  return <p>{formatter.format(0.1534)}</p>;
57
  // "15.3%"
58
}
59

60
// Unit formatting
61
function UnitDisplay() {
62
  const formatter = useNumberFormatter({
63
    style: "unit",
64
    unit: "kilometer-per-hour",
65
    unitDisplay: "short"
66
  });
67
  
68
  return <p>{formatter.format(65)}</p>;
69
  // "65 km/h"
70
}
71

72
// Custom decimal and grouping options
73
function PrecisionNumberDisplay() {
74
  const formatter = useNumberFormatter({
75
    minimumFractionDigits: 2,
76
    maximumFractionDigits: 4,
77
    useGrouping: true
78
  });
79
  
80
  return <p>{formatter.format(1234.5)}</p>;
81
  // "1,234.50"
82
}
83
```
84

85
### Intl.NumberFormat Methods
86

87
The Intl.NumberFormat provides additional methods for advanced formatting needs.
88

89
```typescript { .api }
90
interface Intl.NumberFormat {
91
  /** Format a number to a string */
92
  format(value: number): string;
93
  /** Format a number to an array of parts with type information */
94
  formatToParts(value: number): Intl.NumberFormatPart[];
95
  /** Format a range between two numbers */
96
  formatRange(start: number, end: number): string;
97
  /** Format a range to parts */
98
  formatRangeToParts(start: number, end: number): Intl.NumberFormatPart[];
99
  /** Get resolved formatting options */
100
  resolvedOptions(): Intl.ResolvedNumberFormatOptions;
101
}
102
```
103

104
**Advanced Usage Examples:**
105

106
```typescript
107
function AdvancedNumberFormatting() {
108
  const formatter = useNumberFormatter({
109
    style: "currency",
110
    currency: "EUR",
111
    minimumFractionDigits: 2
112
  });
113
  
114
  const value = 1234.56;
115
  const startValue = 100;
116
  const endValue = 200;
117
  
118
  return (
119
    <div>
120
      {/* Basic formatting */}
121
      <p>Price: {formatter.format(value)}</p>
122
      
123
      {/* Parts formatting for custom styling */}
124
      <p>
125
        Styled: {formatter.formatToParts(value).map((part, i) => (
126
          <span key={i} className={`number-${part.type}`}>
127
            {part.value}
128
          </span>
129
        ))}
130
      </p>
131
      
132
      {/* Range formatting */}
133
      <p>Range: {formatter.formatRange(startValue, endValue)}</p>
134
      
135
      {/* Resolved options */}
136
      <p>Currency: {formatter.resolvedOptions().currency}</p>
137
    </div>
138
  );
139
}
140
```
141

142
### useListFormatter Hook
143

144
Provides localized list formatting for arrays with proper conjunction and disjunction support.
145

146
```typescript { .api }
147
/**
148
 * Provides localized list formatting for the current locale. Automatically updates when the locale changes,
149
 * and handles caching of the list formatter for performance.
150
 * @param options - Formatting options for list presentation
151
 * @returns Intl.ListFormat instance
152
 */
153
function useListFormatter(options?: Intl.ListFormatOptions): Intl.ListFormat;
154

155
interface Intl.ListFormatOptions {
156
  /** The locale matching algorithm to use */
157
  localeMatcher?: "best fit" | "lookup";
158
  /** The type of list */
159
  type?: "conjunction" | "disjunction" | "unit";
160
  /** The style of the list */
161
  style?: "long" | "short" | "narrow";
162
}
163
```
164

165
**Usage Examples:**
166

167
```typescript
168
import { useListFormatter, I18nProvider } from "@react-aria/i18n";
169

170
// Basic list formatting (conjunction - "and")
171
function BasicListDisplay() {
172
  const formatter = useListFormatter({
173
    style: "long",
174
    type: "conjunction"
175
  });
176
  
177
  const items = ["apples", "oranges", "bananas"];  
178
  return <p>{formatter.format(items)}</p>;
179
  // English: "apples, oranges, and bananas"
180
  // Spanish: "apples, oranges y bananas"
181
}
182

183
// Disjunction list formatting ("or")
184
function DisjunctionListDisplay() {
185
  const formatter = useListFormatter({
186
    style: "long",
187
    type: "disjunction"
188
  });
189
  
190
  const options = ["red", "blue", "green"];
191
  return <p>Choose: {formatter.format(options)}</p>;
192
  // English: "red, blue, or green"
193
}
194

195
// Unit list formatting (no conjunctions)
196
function UnitListDisplay() {
197
  const formatter = useListFormatter({
198
    style: "short",
199
    type: "unit"
200
  });
201
  
202
  const measurements = ["5 ft", "10 in"];
203
  return <p>{formatter.format(measurements)}</p>;
204
  // "5 ft, 10 in"
205
}
206

207
// Different styles comparison
208
function ListStyleComparison() {
209
  const longFormatter = useListFormatter({ style: "long" });
210
  const shortFormatter = useListFormatter({ style: "short" });
211
  const narrowFormatter = useListFormatter({ style: "narrow" });
212
  
213
  const items = ["first", "second", "third"];
214
  
215
  return (
216
    <div>
217
      <p>Long: {longFormatter.format(items)}</p>
218
      <p>Short: {shortFormatter.format(items)}</p>
219
      <p>Narrow: {narrowFormatter.format(items)}</p>
220
    </div>
221
  );
222
}
223

224
// Locale-specific list formatting
225
function LocaleSpecificLists() {
226
  const items = ["JavaScript", "TypeScript", "React"];
227
  
228
  return (
229
    <div>
230
      <I18nProvider locale="en-US">
231
        <ListDisplay items={items} />
232
      </I18nProvider>
233
      <I18nProvider locale="de-DE">
234
        <ListDisplay items={items} />
235
      </I18nProvider>
236
      <I18nProvider locale="ja-JP">
237
        <ListDisplay items={items} />
238
      </I18nProvider>
239
    </div>
240
  );
241
}
242

243
function ListDisplay({ items }: { items: string[] }) {
244
  const formatter = useListFormatter();
245
  return <p>{formatter.format(items)}</p>;
246
}
247
```
248

249
### ListFormatter Methods
250

251
Additional methods available on the ListFormat instance.
252

253
```typescript { .api }
254
interface Intl.ListFormat {
255
  /** Format an array of strings to a localized list string */
256
  format(list: string[]): string;
257
  /** Format an array to parts with type information */
258
  formatToParts(list: string[]): Intl.ListFormatPart[];
259
  /** Get resolved formatting options */
260
  resolvedOptions(): Intl.ResolvedListFormatOptions;
261
}
262
```
263

264
**Advanced List Formatting:**
265

266
```typescript
267
function AdvancedListFormatting() {
268
  const formatter = useListFormatter({
269
    style: "long",
270
    type: "conjunction"
271
  });
272
  
273
  const items = ["red", "green", "blue"];
274
  
275
  return (
276
    <div>
277
      {/* Basic formatting */}
278
      <p>Colors: {formatter.format(items)}</p>
279
      
280
      {/* Parts formatting for custom styling */}
281
      <p>
282
        Styled: {formatter.formatToParts(items).map((part, i) => (
283
          <span key={i} className={`list-${part.type}`}>
284
            {part.value}
285
          </span>
286
        ))}
287
      </p>
288
      
289
      {/* Options inspection */}
290
      <p>Style: {formatter.resolvedOptions().style}</p>
291
    </div>
292
  );
293
}
294
```