0
# Number and Date Prompts
1

2
Prompts for numeric and temporal input with specialized controls, validation, and formatting. Number prompts support integer and floating-point input with increment/decrement controls, while date prompts provide interactive date selection with locale support.
3

4
```javascript
5
const prompts = require('prompts');
6
```
7

8
## Capabilities
9

10
### Number Prompt
11

12
Interactive number input prompt with support for integer and floating-point numbers, min/max validation, and arrow key increment/decrement controls.
13

14
```javascript { .api }
15
{
16
  /** Prompt type identifier */
17
  type: 'number',
18
  /** Property name for response object */
19
  name: string,
20
  /** Display message for user */
21
  message: string,
22
  /** Default number value */
23
  initial?: number,
24
  /** Maximum allowed value. Defaults to Infinity */
25
  max?: number,
26
  /** Minimum allowed value. Defaults to -Infinity */
27
  min?: number,
28
  /** Allow floating point inputs. Defaults to false */
29
  float?: boolean,
30
  /** Round float values to x decimals. Defaults to 2 */
31
  round?: number,
32
  /** Increment step when using arrow keys. Defaults to 1 */
33
  increment?: number,
34
  /** Render style controlling input display */
35
  style?: 'default' | 'password' | 'invisible' | 'emoji',
36
  /** Custom formatter for user input */
37
  format?: (value: number, values: Answers) => any,
38
  /** Input validation function */
39
  validate?: (value: number, values: Answers) => boolean | string,
40
  /** Render callback with kleur styling */
41
  onRender?: (kleur: any) => void,
42
  /** State change callback */
43
  onState?: (state: { value: number; aborted: boolean }) => void,
44
  /** Input stream */
45
  stdin?: NodeJS.ReadableStream,
46
  /** Output stream */
47
  stdout?: NodeJS.WritableStream
48
}
49
```
50

51
**Usage Examples:**
52

53
```javascript
54
const prompts = require('prompts');
55

56
// Basic number input
57
const response = await prompts({
58
  type: 'number',
59
  name: 'age',
60
  message: 'How old are you?',
61
  initial: 0,
62
  min: 0,
63
  max: 120
64
});
65

66
// Floating-point number with custom increment
67
const response = await prompts({
68
  type: 'number',
69
  name: 'price',
70
  message: 'Enter price:',
71
  initial: 9.99,
72
  min: 0,
73
  float: true,
74
  round: 2,
75
  increment: 0.50,
76
  format: value => `$${value.toFixed(2)}`
77
});
78

79
// Number with validation
80
const response = await prompts({
81
  type: 'number',
82
  name: 'port',
83
  message: 'Enter port number:',
84
  initial: 3000,
85
  validate: value => {
86
    if (value < 1024) return 'Port must be 1024 or higher';
87
    if (value > 65535) return 'Port must be 65535 or lower';
88
    return true;
89
  }
90
});
91
```
92

93
### Date Prompt
94

95
Interactive date selection prompt with keyboard navigation, locale support, and custom date formatting masks.
96

97
```javascript { .api }
98
{
99
  /** Prompt type identifier */
100
  type: 'date',
101
  /** Property name for response object */
102
  name: string,
103
  /** Display message for user */
104
  message: string,
105
  /** Default date value */
106
  initial?: Date,
107
  /** Custom locales for month/day names */
108
  locales?: DateLocales,
109
  /** Date format mask. Defaults to 'YYYY-MM-DD HH:mm:ss' */
110
  mask?: string,
111
  /** Input validation function */
112
  validate?: (date: Date, values: Answers) => boolean | string,
113
  /** Custom formatter for date value */
114
  format?: (date: Date, values: Answers) => any,
115
  /** Render callback with kleur styling */
116
  onRender?: (kleur: any) => void,
117
  /** State change callback */
118
  onState?: (state: { value: Date; aborted: boolean }) => void,
119
  /** Input stream */
120
  stdin?: NodeJS.ReadableStream,
121
  /** Output stream */
122
  stdout?: NodeJS.WritableStream
123
}
124

125
interface DateLocales {
126
  /** Full month names */
127
  months?: string[];
128
  /** Short month names */
129
  monthsShort?: string[];
130
  /** Full weekday names */
131
  weekdays?: string[];
132
  /** Short weekday names */
133
  weekdaysShort?: string[];
134
}
135
```
136

137
**Usage Examples:**
138

139
```javascript
140
// Basic date input
141
const response = await prompts({
142
  type: 'date',
143
  name: 'birthday',
144
  message: 'Enter your birthday:',
145
  initial: new Date(1990, 0, 1)
146
});
147

148
// Date with validation (no future dates)
149
const response = await prompts({
150
  type: 'date',
151
  name: 'eventDate',
152
  message: 'Enter event date:',
153
  validate: date => {
154
    const now = new Date();
155
    return date > now ? 'Date cannot be in the future' : true;
156
  }
157
});
158

159
// Date with custom format and locales
160
const response = await prompts({
161
  type: 'date',
162
  name: 'appointmentDate',
163
  message: 'Select appointment date:',
164
  mask: 'DD/MM/YYYY',
165
  locales: {
166
    months: [
167
      'Enero', 'Febrero', 'Marzo', 'Abril', 'Mayo', 'Junio',
168
      'Julio', 'Agosto', 'Septiembre', 'Octubre', 'Noviembre', 'Diciembre'
169
    ],
170
    weekdays: [
171
      'Domingo', 'Lunes', 'Martes', 'Miércoles', 
172
      'Jueves', 'Viernes', 'Sábado'
173
    ]
174
  },
175
  format: date => date.toLocaleDateString('es-ES')
176
});
177
```
178

179
## Date Formatting Masks
180

181
The date prompt supports various formatting masks for display:
182

183
### Common Mask Patterns
184

185
```javascript { .api }
186
// Year formats
187
'YYYY' // 2023 (4-digit year)
188
'YY'   // 23 (2-digit year)
189

190
// Month formats  
191
'MM'   // 01-12 (2-digit month)
192
'M'    // 1-12 (1-digit month)
193
'MMMM' // January (full month name)
194
'MMM'  // Jan (short month name)
195

196
// Day formats
197
'DD'   // 01-31 (2-digit day)
198
'D'    // 1-31 (1-digit day)
199
'dddd' // Monday (full weekday name)
200
'ddd'  // Mon (short weekday name)
201

202
// Time formats
203
'HH'   // 00-23 (24-hour format)
204
'hh'   // 01-12 (12-hour format)
205
'mm'   // 00-59 (minutes)
206
'ss'   // 00-59 (seconds)
207
'SSS'  // 000-999 (milliseconds)
208
'A'    // AM/PM
209
```
210

211
**Usage Examples:**
212

213
```javascript
214
// Different date format examples
215
const formats = [
216
  'YYYY-MM-DD',           // 2023-12-25
217
  'DD/MM/YYYY',           // 25/12/2023
218
  'MMMM D, YYYY',         // December 25, 2023
219
  'dddd, MMM D, YYYY',    // Monday, Dec 25, 2023
220
  'YYYY-MM-DD HH:mm:ss',  // 2023-12-25 14:30:00
221
  'hh:mm A'               // 02:30 PM
222
];
223
```
224

225
## Default Date Locales
226

227
The default English locales provided by the date prompt:
228

229
```javascript { .api }
230
const defaultLocales = {
231
  months: [
232
    'January', 'February', 'March', 'April',
233
    'May', 'June', 'July', 'August', 
234
    'September', 'October', 'November', 'December'
235
  ],
236
  monthsShort: [
237
    'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
238
    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
239
  ],
240
  weekdays: [
241
    'Sunday', 'Monday', 'Tuesday', 'Wednesday',
242
    'Thursday', 'Friday', 'Saturday'
243
  ],
244
  weekdaysShort: [
245
    'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'
246
  ]
247
};
248
```
249

250
## Number Prompt Behavior
251

252
### Input Controls
253
- **Arrow Up/Down**: Increment/decrement by the `increment` value
254
- **Tab key**: Autocomplete to initial value when provided
255
- **Number keys**: Direct numeric input
256
- **Decimal point**: For float inputs when `float: true`
257
- **Backspace**: Delete characters
258
- **Enter**: Submit current value
259
- **Escape**: Cancel prompt
260

261
### Number Validation
262
- Input is automatically parsed as integer or float based on `float` setting
263
- Min/max validation is applied automatically
264
- Custom validation function receives the parsed number value
265
- Invalid numeric input shows error message and allows retry
266

267
## Date Prompt Behavior
268

269
### Navigation Controls
270
- **Left/Right Arrow**: Navigate between date components (day/month/year/time)
271
- **Up/Down Arrow**: Increment/decrement the selected component
272
- **Tab**: Move to next date component
273
- **Enter**: Submit current date
274
- **Escape**: Cancel prompt
275

276
### Date Components
277
- **Year**: 4-digit year input with arrow key increment/decrement
278
- **Month**: Month selection with full/short name display
279
- **Day**: Day of month with validation for month/year
280
- **Hour**: 24-hour or 12-hour format based on mask
281
- **Minute/Second**: Time components with 60-value range
282
- **Meridiem**: AM/PM for 12-hour time format
283

284
### Date Validation
285
- Automatic validation for valid dates (e.g., no February 30)
286
- Custom validation function receives Date object
287
- Invalid dates are prevented during navigation
288
- Custom validation messages for business logic (e.g., no weekends)