0
# Text Input Prompts
1

2
Text-based input prompts for gathering string input from users, including standard text input, password (masked) input, and invisible input modes. All text prompts support validation, formatting, and autocomplete to initial value.
3

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

8
## Capabilities
9

10
### Text Prompt
11

12
Standard text input prompt for free text entry. Users can type freely and use Tab to autocomplete to the initial value when provided.
13

14
```javascript { .api }
15
{
16
  /** Prompt type identifier */
17
  type: 'text',
18
  /** Property name for response object */
19
  name: string,
20
  /** Display message for user */
21
  message: string,
22
  /** Default string value. User can Tab to autocomplete to this value */
23
  initial?: string,
24
  /** Render style controlling input visibility */
25
  style?: 'default' | 'password' | 'invisible' | 'emoji',
26
  /** Custom formatter for user input */
27
  format?: (value: string, values: Answers) => any,
28
  /** Input validation function */
29
  validate?: (value: string, values: Answers) => boolean | string,
30
  /** Render callback with kleur styling */
31
  onRender?: (kleur: any) => void,
32
  /** State change callback */
33
  onState?: (state: { value: string; aborted: boolean }) => void,
34
  /** Input stream */
35
  stdin?: NodeJS.ReadableStream,
36
  /** Output stream */
37
  stdout?: NodeJS.WritableStream
38
}
39
```
40

41
**Usage Examples:**
42

43
```javascript
44
const prompts = require('prompts');
45

46
// Basic text input
47
const response = await prompts({
48
  type: 'text',
49
  name: 'username',
50
  message: 'What is your GitHub username?'
51
});
52

53
// Text input with validation and formatting
54
const response = await prompts({
55
  type: 'text',
56
  name: 'email',
57
  message: 'Enter your email address:',
58
  initial: 'user@example.com',
59
  validate: value => {
60
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
61
    return emailRegex.test(value) || 'Please enter a valid email address';
62
  },
63
  format: value => value.toLowerCase().trim()
64
});
65

66
// Text input with custom styling
67
const response = await prompts({
68
  type: 'text',
69
  name: 'message',
70
  message: 'Enter a message:',
71
  style: 'emoji',
72
  onRender(kleur) {
73
    this.msg = kleur.cyan('📝 Enter a message:');
74
  }
75
});
76
```
77

78
### Password Prompt
79

80
Password input prompt with masked display. Input characters are shown as asterisks or dots to hide sensitive information. This is equivalent to using text prompt with `style: 'password'`.
81

82
```javascript { .api }
83
{
84
  /** Prompt type identifier */
85
  type: 'password',
86
  /** Property name for response object */
87
  name: string,
88
  /** Display message for user */
89
  message: string,
90
  /** Default string value (not recommended for passwords) */
91
  initial?: string,
92
  /** Custom formatter for user input */
93
  format?: (value: string, values: Answers) => any,
94
  /** Input validation function */
95
  validate?: (value: string, values: Answers) => boolean | string,
96
  /** Render callback with kleur styling */
97
  onRender?: (kleur: any) => void,
98
  /** State change callback */
99
  onState?: (state: { value: string; aborted: boolean }) => void,
100
  /** Input stream */
101
  stdin?: NodeJS.ReadableStream,
102
  /** Output stream */
103
  stdout?: NodeJS.WritableStream
104
}
105
```
106

107
**Usage Examples:**
108

109
```javascript
110
// Basic password input
111
const response = await prompts({
112
  type: 'password',
113
  name: 'password',
114
  message: 'Enter your password:'
115
});
116

117
// Password with validation
118
const response = await prompts({
119
  type: 'password',
120
  name: 'newPassword',
121
  message: 'Create a new password:',
122
  validate: value => {
123
    if (value.length < 8) return 'Password must be at least 8 characters';
124
    if (!/[A-Z]/.test(value)) return 'Password must contain an uppercase letter';
125
    if (!/[0-9]/.test(value)) return 'Password must contain a number';
126
    return true;
127
  }
128
});
129

130
// Password confirmation
131
const questions = [
132
  {
133
    type: 'password',
134
    name: 'password',
135
    message: 'Enter password:'
136
  },
137
  {
138
    type: 'password', 
139
    name: 'confirmPassword',
140
    message: 'Confirm password:',
141
    validate: (value, values) => 
142
      value === values.password || 'Passwords do not match'
143
  }
144
];
145
```
146

147
### Invisible Prompt
148

149
Invisible input prompt where user input is completely hidden, similar to sudo password prompts. This is equivalent to using text prompt with `style: 'invisible'`.
150

151
```javascript { .api }
152
{
153
  /** Prompt type identifier */
154
  type: 'invisible',
155
  /** Property name for response object */
156
  name: string,
157
  /** Display message for user */
158
  message: string,
159
  /** Default string value */
160
  initial?: string,
161
  /** Custom formatter for user input */
162
  format?: (value: string, values: Answers) => any,
163
  /** Input validation function */
164
  validate?: (value: string, values: Answers) => boolean | string,
165
  /** Render callback with kleur styling */
166
  onRender?: (kleur: any) => void,
167
  /** State change callback */
168
  onState?: (state: { value: string; aborted: boolean }) => void,
169
  /** Input stream */
170
  stdin?: NodeJS.ReadableStream,
171
  /** Output stream */
172
  stdout?: NodeJS.WritableStream
173
}
174
```
175

176
**Usage Examples:**
177

178
```javascript
179
// Invisible input for sensitive data
180
const response = await prompts({
181
  type: 'invisible',
182
  name: 'secret',
183
  message: 'Enter your secret key:'
184
});
185

186
// Invisible input with validation
187
const response = await prompts({
188
  type: 'invisible',
189
  name: 'apiKey',
190
  message: 'Enter API key:',
191
  validate: value => {
192
    if (!value) return 'API key is required';
193
    if (value.length !== 32) return 'API key must be 32 characters';
194
    return true;
195
  },
196
  format: value => value.trim()
197
});
198
```
199

200
### List Prompt
201

202
List input prompt that splits user input into an array using a specified separator. The output is an array containing the trimmed string values.
203

204
```javascript { .api }
205
{
206
  /** Prompt type identifier */
207
  type: 'list',
208
  /** Property name for response object */
209
  name: string,
210
  /** Display message for user */
211
  message: string,
212
  /** Default string value */
213
  initial?: string,
214
  /** String separator for splitting input. Defaults to comma ',' */
215
  separator?: string,
216
  /** Input style */
217
  style?: 'default' | 'password' | 'invisible' | 'emoji',
218
  /** Custom formatter for the resulting array */
219
  format?: (value: string[], values: Answers) => any,
220
  /** Render callback with kleur styling */
221
  onRender?: (kleur: any) => void,
222
  /** State change callback */
223
  onState?: (state: { value: string; aborted: boolean }) => void,
224
  /** Input stream */
225
  stdin?: NodeJS.ReadableStream,
226
  /** Output stream */
227
  stdout?: NodeJS.WritableStream
228
}
229
```
230

231
**Usage Examples:**
232

233
```javascript
234
// Basic list input with comma separator
235
const response = await prompts({
236
  type: 'list',
237
  name: 'keywords',
238
  message: 'Enter keywords (comma separated):',
239
  initial: 'javascript, node, cli'
240
});
241
// Result: { keywords: ['javascript', 'node', 'cli'] }
242

243
// List input with custom separator
244
const response = await prompts({
245
  type: 'list',
246
  name: 'paths',
247
  message: 'Enter file paths (semicolon separated):',
248
  separator: ';'
249
});
250

251
// List input with validation and formatting
252
const response = await prompts({
253
  type: 'list',
254
  name: 'emails',
255
  message: 'Enter email addresses:',
256
  validate: (values) => {
257
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
258
    const invalid = values.find(email => !emailRegex.test(email));
259
    return invalid ? `Invalid email: ${invalid}` : true;
260
  },
261
  format: (values) => values.map(email => email.toLowerCase())
262
});
263
```
264

265
## Text Prompt Behavior
266

267
### Input Handling
268
- **Tab key**: Autocompletes to the initial value when provided
269
- **Enter key**: Submits the current input value
270
- **Escape key**: Cancels the prompt
271
- **Ctrl+C/Ctrl+D**: Aborts the prompt
272

273
### Style Options
274
- **default**: Normal text input (characters visible)
275
- **password**: Masked input (shows * or • characters)
276
- **invisible**: Completely hidden input (no visual feedback)
277
- **emoji**: Allows emoji input and display
278

279
### Validation
280
- Validation function is called on submit, not during typing
281
- Return `true` for valid input
282
- Return error message string for invalid input
283
- Return `false` for invalid input with default error message
284
- Supports async validation with Promise return
285

286
### Formatting
287
- Format function is called after validation passes
288
- Receives the raw user input and all previous answers
289
- Return value is stored in the response object
290
- Supports async formatting with Promise return