0
# Input Components
1

2
Input components provide comprehensive form controls with built-in validation, accessibility features, and consistent styling. All input components share common field properties and behaviors.
3

4
## Capabilities
5

6
### Text Field
7

8
Basic text input field with comprehensive validation and formatting support.
9

10
```typescript { .api }
11
/**
12
 * Base text input field component
13
 * Provides foundation for all text-based input controls
14
 */
15
interface TextField extends HTMLElement {
16
  /** Current field value */
17
  value: string;
18
  /** Field label displayed above input */
19
  label: string;
20
  /** Placeholder text when field is empty */
21
  placeholder: string;
22
  /** Field is required for form submission */
23
  required: boolean;
24
  /** Field is read-only (not editable) */
25
  readonly: boolean;
26
  /** Field is disabled (not interactive) */
27
  disabled: boolean;
28
  /** Field has validation errors */
29
  invalid: boolean;
30
  /** Error message displayed when invalid */
31
  errorMessage: string;
32
  /** Helper text displayed below field */
33
  helperText: string;
34
  /** HTML input type attribute */
35
  type: string;
36
  /** Regular expression pattern for validation */
37
  pattern: string;
38
  /** Minimum text length */
39
  minlength: number;
40
  /** Maximum text length */
41
  maxlength: number;
42
  /** Autocomplete behavior hint */
43
  autocomplete: string;
44
  /** Automatic capitalization behavior */
45
  autocapitalize: string;
46
  /** Automatic text correction behavior */
47
  autocorrect: string;
48

49
  /** Validate field value against constraints */
50
  validate(): boolean;
51
  /** Check HTML5 validity constraints */
52
  checkValidity(): boolean;
53
  /** Focus the input field */
54
  focus(): void;
55
  /** Select all text in the field */
56
  select(): void;
57
  /** Clear the field value */
58
  clear(): void;
59
}
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
import '@vaadin/text-field';
66

67
const textField = document.createElement('vaadin-text-field');
68
textField.label = 'Full Name';
69
textField.placeholder = 'Enter your full name';
70
textField.required = true;
71
textField.helperText = 'First and last name';
72

73
// Validation
74
textField.addEventListener('input', () => {
75
  if (textField.value.length < 2) {
76
    textField.invalid = true;
77
    textField.errorMessage = 'Name must be at least 2 characters';
78
  } else {
79
    textField.invalid = false;
80
  }
81
});
82

83
// Form submission
84
const form = document.querySelector('form');
85
form.addEventListener('submit', (e) => {
86
  if (!textField.validate()) {
87
    e.preventDefault();
88
  }
89
});
90
```
91

92
### Password Field
93

94
Password input with visibility toggle and security features.
95

96
```typescript { .api }
97
/**
98
 * Password input field with reveal/hide functionality
99
 * Extends TextField with password-specific features
100
 */
101
interface PasswordField extends TextField {
102
  /** Controls password visibility (show/hide) */
103
  passwordVisible: boolean;
104
  /** Title for the reveal button */
105
  revealButtonTitle: string;
106
  /** Hidden title for the reveal button */
107
  revealButtonHiddenTitle: string;
108
}
109
```
110

111
### Email Field
112

113
Email input with built-in email validation.
114

115
```typescript { .api }
116
/**
117
 * Email input field with automatic email validation
118
 * Validates input against standard email format
119
 */
120
interface EmailField extends TextField {
121
  /** Inherits all TextField properties with email validation */
122
}
123
```
124

125
### Number Field
126

127
Numeric input with increment/decrement controls and range validation.
128

129
```typescript { .api }
130
/**
131
 * Numeric input field with stepper controls
132
 * Supports integer and decimal number input with validation
133
 */
134
interface NumberField extends TextField {
135
  /** Minimum allowed value */
136
  min: number;
137
  /** Maximum allowed value */
138
  max: number;
139
  /** Step increment for +/- controls */
140
  step: number;
141

142
  /** Increase value by step amount */
143
  stepUp(increment?: number): void;
144
  /** Decrease value by step amount */
145
  stepDown(decrement?: number): void;
146
}
147
```
148

149
**Usage Examples:**
150

151
```typescript
152
import '@vaadin/number-field';
153

154
const priceField = document.createElement('vaadin-number-field');
155
priceField.label = 'Price';
156
priceField.min = 0;
157
priceField.max = 10000;
158
priceField.step = 0.01; // Two decimal places
159
priceField.value = '99.99';
160

161
// Format value display
162
priceField.addEventListener('blur', () => {
163
  const value = parseFloat(priceField.value);
164
  if (!isNaN(value)) {
165
    priceField.value = value.toFixed(2);
166
  }
167
});
168
```
169

170
### Integer Field
171

172
Integer-only numeric input restricting decimal values.
173

174
```typescript { .api }
175
/**
176
 * Integer input field restricting decimal values
177
 * Only allows whole number input
178
 */
179
interface IntegerField extends NumberField {
180
  /** Inherits NumberField properties, restricted to integers */
181
}
182
```
183

184
### Text Area
185

186
Multi-line text input for longer content.
187

188
```typescript { .api }
189
/**
190
 * Multi-line text input area
191
 * Supports automatic resizing and character limits
192
 */
193
interface TextArea extends TextField {
194
  /** Minimum character length */
195
  minlength: number;
196
  /** Maximum character length */
197
  maxlength: number;
198
  /** Number of visible text rows */
199
  rows: number;
200
  /** Maximum number of rows before scrolling */
201
  maxRows: number;
202
}
203
```
204

205
**Usage Examples:**
206

207
```typescript
208
import '@vaadin/text-area';
209

210
const descriptionArea = document.createElement('vaadin-text-area');
211
descriptionArea.label = 'Description';
212
descriptionArea.placeholder = 'Enter a detailed description...';
213
descriptionArea.maxlength = 500;
214
descriptionArea.rows = 4;
215
descriptionArea.maxRows = 10;
216

217
// Character counter
218
descriptionArea.addEventListener('input', () => {
219
  const remaining = descriptionArea.maxlength - descriptionArea.value.length;
220
  descriptionArea.helperText = `${remaining} characters remaining`;
221
});
222
```
223

224
### Checkbox
225

226
Boolean input control for true/false selections.
227

228
```typescript { .api }
229
/**
230
 * Checkbox input for boolean values
231
 * Supports checked, unchecked, and indeterminate states
232
 */
233
interface Checkbox extends HTMLElement {
234
  /** Current checked state */
235
  checked: boolean;
236
  /** Indeterminate state (partially checked) */
237
  indeterminate: boolean;
238
  /** Checkbox is disabled */
239
  disabled: boolean;
240
  /** Checkbox is read-only */
241
  readonly: boolean;
242
  /** Form name attribute */
243
  name: string;
244
  /** Form value when checked */
245
  value: string;
246
  /** Label text */
247
  label: string;
248

249
  /** Programmatically click checkbox */
250
  click(): void;
251
  /** Focus the checkbox */
252
  focus(): void;
253
}
254
```
255

256
### Checkbox Group
257

258
Group of related checkboxes for multiple selections.
259

260
```typescript { .api }
261
/**
262
 * Group of checkboxes for multiple selection
263
 * Manages collection of related boolean choices
264
 */
265
interface CheckboxGroup extends HTMLElement {
266
  /** Array of selected values */
267
  value: string[];
268
  /** Group label */
269
  label: string;
270
  /** Group is disabled */
271
  disabled: boolean;
272
  /** Group is read-only */
273
  readonly: boolean;
274
  /** Group is required (at least one must be selected) */
275
  required: boolean;
276
  /** Group has validation errors */
277
  invalid: boolean;
278
  /** Error message when invalid */
279
  errorMessage: string;
280

281
  /** Validate group selection */
282
  validate(): boolean;
283
  /** Check validity of selection */
284
  checkValidity(): boolean;
285
}
286
```
287

288
**Usage Examples:**
289

290
```typescript
291
import '@vaadin/checkbox-group';
292

293
const interestsGroup = document.createElement('vaadin-checkbox-group');
294
interestsGroup.label = 'Interests';
295
interestsGroup.innerHTML = `
296
  <vaadin-checkbox value="sports" label="Sports"></vaadin-checkbox>
297
  <vaadin-checkbox value="music" label="Music"></vaadin-checkbox>
298
  <vaadin-checkbox value="travel" label="Travel"></vaadin-checkbox>
299
`;
300

301
// Handle selection changes
302
interestsGroup.addEventListener('value-changed', (e) => {
303
  console.log('Selected interests:', e.detail.value);
304
});
305
```
306

307
### Radio Group
308

309
Group of radio buttons for single selection from multiple options.
310

311
```typescript { .api }
312
/**
313
 * Group of radio buttons for single selection
314
 * Manages mutually exclusive choices
315
 */
316
interface RadioGroup extends HTMLElement {
317
  /** Selected value */
318
  value: string;
319
  /** Group label */
320
  label: string;
321
  /** Group is disabled */
322
  disabled: boolean;
323
  /** Group is read-only */
324
  readonly: boolean;
325
  /** Group is required */
326
  required: boolean;
327
  /** Group has validation errors */
328
  invalid: boolean;
329
  /** Error message when invalid */
330
  errorMessage: string;
331

332
  /** Validate group selection */
333
  validate(): boolean;
334
  /** Check validity of selection */
335
  checkValidity(): boolean;
336
}
337

338
/**
339
 * Individual radio button within RadioGroup
340
 */
341
interface RadioButton extends HTMLElement {
342
  /** Radio button value */
343
  value: string;
344
  /** Radio button is checked */
345
  checked: boolean;
346
  /** Radio button label */
347
  label: string;
348
  /** Radio button is disabled */
349
  disabled: boolean;
350
}
351
```
352

353
### Custom Field
354

355
Container for creating composite form fields from multiple input components.
356

357
```typescript { .api }
358
/**
359
 * Container for creating custom composite fields
360
 * Combines multiple input components into single field
361
 */
362
interface CustomField extends HTMLElement {
363
  /** Combined field value */
364
  value: string;
365
  /** Field label */
366
  label: string;
367
  /** Field is required */
368
  required: boolean;
369
  /** Field is disabled */
370
  disabled: boolean;
371
  /** Field is read-only */
372
  readonly: boolean;
373
  /** Field has validation errors */
374
  invalid: boolean;
375
  /** Error message when invalid */
376
  errorMessage: string;
377
  /** Helper text */
378
  helperText: string;
379

380
  /** Child input elements */
381
  readonly inputs: Element[];
382
  /** Validate all child inputs */
383
  checkValidity(): boolean;
384
  /** Validate custom field logic */
385
  validate(): boolean;
386
}
387
```
388

389
**Usage Examples:**
390

391
```typescript
392
import '@vaadin/custom-field';
393

394
// Create phone number field with separate inputs
395
const phoneField = document.createElement('vaadin-custom-field');
396
phoneField.label = 'Phone Number';
397

398
const areaCode = document.createElement('vaadin-text-field');
399
areaCode.placeholder = '123';
400
areaCode.maxlength = 3;
401
areaCode.style.width = '80px';
402

403
const exchange = document.createElement('vaadin-text-field');
404
exchange.placeholder = '456';
405
exchange.maxlength = 3;
406
exchange.style.width = '80px';
407

408
const number = document.createElement('vaadin-text-field');
409
number.placeholder = '7890';
410
number.maxlength = 4;
411
number.style.width = '100px';
412

413
phoneField.appendChild(areaCode);
414
phoneField.appendChild(exchange);
415
phoneField.appendChild(number);
416

417
// Custom validation and value handling
418
phoneField.addEventListener('change', () => {
419
  const fullNumber = `${areaCode.value}-${exchange.value}-${number.value}`;
420
  phoneField.value = fullNumber;
421
});
422
```
423

424
## Validation Patterns
425

426
### Basic Validation
427

428
```typescript
429
// Standard field validation
430
const validateField = (field: TextField) => {
431
  let isValid = true;
432

433
  // Required validation
434
  if (field.required && !field.value.trim()) {
435
    field.errorMessage = 'This field is required';
436
    field.invalid = true;
437
    isValid = false;
438
  }
439

440
  // Length validation
441
  else if (field.minlength && field.value.length < field.minlength) {
442
    field.errorMessage = `Minimum ${field.minlength} characters required`;
443
    field.invalid = true;
444
    isValid = false;
445
  }
446

447
  // Pattern validation
448
  else if (field.pattern && !new RegExp(field.pattern).test(field.value)) {
449
    field.errorMessage = 'Invalid format';
450
    field.invalid = true;
451
    isValid = false;
452
  }
453

454
  else {
455
    field.invalid = false;
456
  }
457

458
  return isValid;
459
};
460
```
461

462
### Form Validation
463

464
```typescript
465
// Complete form validation
466
const validateForm = (form: HTMLFormElement) => {
467
  const fields = form.querySelectorAll('vaadin-text-field, vaadin-email-field, vaadin-password-field');
468
  let formValid = true;
469

470
  fields.forEach(field => {
471
    if (!field.validate()) {
472
      formValid = false;
473
    }
474
  });
475

476
  return formValid;
477
};
478
```