0
# Form Components
1

2
Interactive form controls with Material Design styling and behavior including buttons, text fields, checkboxes, radio buttons, switches, and sliders. All form components provide both visual styling and programmatic APIs for dynamic interaction.
3

4
## Capabilities
5

6
### Material Button
7

8
Enhanced button with ripple effects and state management.
9

10
```javascript { .api }
11
/**
12
 * Material Design button component
13
 * CSS Class: mdl-js-button
14
 * Widget: true
15
 */
16
interface MaterialButton {
17
  /** Disable the button, preventing interaction and adding disabled styling */
18
  disable(): void;
19
  
20
  /** Enable the button, restoring interaction and removing disabled styling */
21
  enable(): void;
22
}
23
```
24

25
**HTML Structure:**
26

27
```html
28
<!-- Basic button -->
29
<button class="mdl-button mdl-js-button">
30
  Button
31
</button>
32

33
<!-- Raised button with ripple effect -->
34
<button class="mdl-button mdl-js-button mdl-button--raised mdl-js-ripple-effect">
35
  Raised Button
36
</button>
37

38
<!-- FAB (Floating Action Button) -->
39
<button class="mdl-button mdl-js-button mdl-button--fab mdl-button--colored">
40
  <i class="material-icons">add</i>
41
</button>
42
```
43

44
**Usage Examples:**
45

46
```javascript
47
// Access button instance
48
const button = document.querySelector('.mdl-js-button').MaterialButton;
49

50
// Disable button programmatically
51
button.disable();
52

53
// Enable button programmatically
54
button.enable();
55

56
// Toggle button state based on form validation
57
function updateButtonState(isValid) {
58
  if (isValid) {
59
    button.enable();
60
  } else {
61
    button.disable();
62
  }
63
}
64
```
65

66
### Material Textfield
67

68
Enhanced text input with floating labels, validation, and state management.
69

70
```javascript { .api }
71
/**
72
 * Material Design text field component
73
 * CSS Class: mdl-js-textfield  
74
 * Widget: true
75
 */
76
interface MaterialTextfield {
77
  /** Check and update disabled state based on input element */
78
  checkDisabled(): void;
79
  
80
  /** Check and update focus state, managing floating label */
81
  checkFocus(): void;
82
  
83
  /** Check and update validity state, showing/hiding error messages */
84
  checkValidity(): void;
85
  
86
  /** Check and update dirty state (whether user has entered content) */
87
  checkDirty(): void;
88
  
89
  /** Disable the textfield, preventing interaction */
90
  disable(): void;
91
  
92
  /** Enable the textfield, restoring interaction */
93
  enable(): void;
94
  
95
  /** 
96
   * Update textfield value and refresh all states
97
   * @param value - New value to set
98
   */
99
  change(value: string): void;
100
}
101
```
102

103
**HTML Structure:**
104

105
```html
106
<!-- Basic textfield with floating label -->
107
<div class="mdl-textfield mdl-js-textfield mdl-textfield--floating-label">
108
  <input class="mdl-textfield__input" type="text" id="sample1">
109
  <label class="mdl-textfield__label" for="sample1">Text...</label>
110
</div>
111

112
<!-- Textfield with error message -->
113
<div class="mdl-textfield mdl-js-textfield mdl-textfield--floating-label">
114
  <input class="mdl-textfield__input" type="email" id="sample2" required>
115
  <label class="mdl-textfield__label" for="sample2">Email...</label>
116
  <span class="mdl-textfield__error">Input is not an email address!</span>
117
</div>
118

119
<!-- Multiline textfield -->
120
<div class="mdl-textfield mdl-js-textfield">
121
  <textarea class="mdl-textfield__input" type="text" rows="3" id="sample5"></textarea>
122
  <label class="mdl-textfield__label" for="sample5">Text lines...</label>
123
</div>
124
```
125

126
**Usage Examples:**
127

128
```javascript
129
// Access textfield instance
130
const textfield = document.querySelector('.mdl-js-textfield').MaterialTextfield;
131

132
// Update value programmatically
133
textfield.change('New value');
134

135
// Check validity after programmatic changes
136
textfield.checkValidity();
137

138
// Disable/enable based on conditions
139
if (userCannotEdit) {
140
  textfield.disable();
141
} else {
142
  textfield.enable();
143
}
144

145
// Validate on blur
146
const input = document.querySelector('.mdl-textfield__input');
147
input.addEventListener('blur', () => {
148
  textfield.checkValidity();
149
  textfield.checkDirty();
150
});
151
```
152

153
### Material Checkbox
154

155
Enhanced checkbox with Material Design styling and state management.
156

157
```javascript { .api }
158
/**
159
 * Material Design checkbox component
160
 * CSS Class: mdl-js-checkbox
161
 * Widget: true
162
 */
163
interface MaterialCheckbox {
164
  /** Check and update toggle state based on input element */
165
  checkToggleState(): void;
166
  
167
  /** Check and update disabled state */
168
  checkDisabled(): void;
169
  
170
  /** Disable the checkbox, preventing interaction */
171
  disable(): void;
172
  
173
  /** Enable the checkbox, restoring interaction */
174
  enable(): void;
175
  
176
  /** Check the checkbox programmatically */
177
  check(): void;
178
  
179
  /** Uncheck the checkbox programmatically */
180
  uncheck(): void;
181
}
182
```
183

184
**HTML Structure:**
185

186
```html
187
<!-- Basic checkbox -->
188
<label class="mdl-checkbox mdl-js-checkbox mdl-js-ripple-effect" for="checkbox-1">
189
  <input type="checkbox" id="checkbox-1" class="mdl-checkbox__input">
190
  <span class="mdl-checkbox__label">Check me out</span>
191
</label>
192

193
<!-- Disabled checkbox -->
194
<label class="mdl-checkbox mdl-js-checkbox mdl-js-ripple-effect" for="checkbox-2">
195
  <input type="checkbox" id="checkbox-2" class="mdl-checkbox__input" disabled>
196
  <span class="mdl-checkbox__label">Disabled</span>
197
</label>
198
```
199

200
**Usage Examples:**
201

202
```javascript
203
// Access checkbox instance
204
const checkbox = document.querySelector('.mdl-js-checkbox').MaterialCheckbox;
205

206
// Check/uncheck programmatically
207
checkbox.check();
208
checkbox.uncheck();
209

210
// Toggle based on condition
211
if (shouldBeChecked) {
212
  checkbox.check();
213
} else {
214
  checkbox.uncheck();
215
}
216

217
// Disable during async operations
218
async function performAsyncAction() {
219
  checkbox.disable();
220
  try {
221
    await someAsyncOperation();
222
  } finally {
223
    checkbox.enable();
224
  }
225
}
226
```
227

228
### Material Radio
229

230
Enhanced radio button with Material Design styling and state management.
231

232
```javascript { .api }
233
/**
234
 * Material Design radio button component
235
 * CSS Class: mdl-js-radio
236
 * Widget: true
237
 */
238
interface MaterialRadio {
239
  /** Check and update toggle state based on input element */
240
  checkToggleState(): void;
241
  
242
  /** Check and update disabled state */
243
  checkDisabled(): void;
244
  
245
  /** Disable the radio button, preventing interaction */
246
  disable(): void;
247
  
248
  /** Enable the radio button, restoring interaction */
249
  enable(): void;
250
  
251
  /** Check the radio button programmatically */
252
  check(): void;
253
  
254
  /** Uncheck the radio button programmatically */
255
  uncheck(): void;
256
}
257
```
258

259
**HTML Structure:**
260

261
```html
262
<!-- Radio button group -->
263
<label class="mdl-radio mdl-js-radio mdl-js-ripple-effect" for="option-1">
264
  <input type="radio" id="option-1" class="mdl-radio__button" name="options" value="1">
265
  <span class="mdl-radio__label">First</span>
266
</label>
267

268
<label class="mdl-radio mdl-js-radio mdl-js-ripple-effect" for="option-2">
269
  <input type="radio" id="option-2" class="mdl-radio__button" name="options" value="2">
270
  <span class="mdl-radio__label">Second</span>
271
</label>
272
```
273

274
### Material Switch
275

276
Toggle switch component for binary state selection.
277

278
```javascript { .api }
279
/**
280
 * Material Design switch component
281
 * CSS Class: mdl-js-switch
282
 * Widget: true
283
 */
284
interface MaterialSwitch {
285
  /** Check and update toggle state based on input element */
286
  checkToggleState(): void;
287
  
288
  /** Check and update disabled state */
289
  checkDisabled(): void;
290
  
291
  /** Disable the switch, preventing interaction */
292
  disable(): void;
293
  
294
  /** Enable the switch, restoring interaction */
295
  enable(): void;
296
  
297
  /** Turn the switch on programmatically */
298
  on(): void;
299
  
300
  /** Turn the switch off programmatically */
301
  off(): void;
302
}
303
```
304

305
**HTML Structure:**
306

307
```html
308
<!-- Basic switch -->
309
<label class="mdl-switch mdl-js-switch mdl-js-ripple-effect" for="switch-1">
310
  <input type="checkbox" id="switch-1" class="mdl-switch__input">
311
  <span class="mdl-switch__label">Enable notifications</span>
312
</label>
313
```
314

315
### Material Icon Toggle
316

317
Icon that toggles between states when clicked.
318

319
```javascript { .api }
320
/**
321
 * Material Design icon toggle component
322
 * CSS Class: mdl-js-icon-toggle
323
 * Widget: true
324
 */
325
interface MaterialIconToggle {
326
  /** Check and update toggle state based on input element */
327
  checkToggleState(): void;
328
  
329
  /** Check and update disabled state */
330
  checkDisabled(): void;
331
  
332
  /** Disable the icon toggle, preventing interaction */
333
  disable(): void;
334
  
335
  /** Enable the icon toggle, restoring interaction */
336
  enable(): void;
337
  
338
  /** Check the icon toggle programmatically */
339
  check(): void;
340
  
341
  /** Uncheck the icon toggle programmatically */
342
  uncheck(): void;
343
}
344
```
345

346
**HTML Structure:**
347

348
```html
349
<!-- Icon toggle for favorites -->
350
<label class="mdl-icon-toggle mdl-js-icon-toggle mdl-js-ripple-effect" for="icon-toggle-1">
351
  <input type="checkbox" id="icon-toggle-1" class="mdl-icon-toggle__input">
352
  <i class="mdl-icon-toggle__label material-icons">favorite_border</i>
353
</label>
354
```
355

356
### Material Slider
357

358
Range slider input component for selecting numeric values.
359

360
```javascript { .api }
361
/**
362
 * Material Design slider component
363
 * CSS Class: mdl-js-slider
364
 * Widget: true
365
 */
366
interface MaterialSlider {
367
  /** Disable the slider, preventing interaction */
368
  disable(): void;
369
  
370
  /** Enable the slider, restoring interaction */
371
  enable(): void;
372
  
373
  /** 
374
   * Update slider value programmatically
375
   * @param value - New value to set (within min/max range)
376
   */
377
  change(value: number): void;
378
}
379

380
// Note: MaterialSlider includes special handling for Internet Explorer compatibility
381
// and automatically creates background container elements for visual styling
382
```
383

384
**HTML Structure:**
385

386
```html
387
<!-- Basic slider -->
388
<p style="width: 300px">
389
  <input class="mdl-slider mdl-js-slider" type="range" 
390
         min="0" max="100" value="0" tabindex="0">
391
</p>
392

393
<!-- Slider with initial value -->
394
<p style="width: 300px">
395
  <input class="mdl-slider mdl-js-slider" type="range" 
396
         min="0" max="100" value="25" tabindex="0">
397
</p>
398
```
399

400
**Usage Examples:**
401

402
```javascript
403
// Access slider instance
404
const slider = document.querySelector('.mdl-js-slider').MaterialSlider;
405

406
// Update value programmatically
407
slider.change(75);
408

409
// Disable during loading
410
slider.disable();
411
// ... perform async operation
412
slider.enable();
413

414
// React to value changes
415
const sliderInput = document.querySelector('.mdl-js-slider');
416
sliderInput.addEventListener('input', (event) => {
417
  console.log('Slider value:', event.target.value);
418
  updateDisplay(event.target.value);
419
});
420
```
421

422
## Form Validation Integration
423

424
```javascript
425
// Integrate with form validation
426
function validateForm() {
427
  const textfields = document.querySelectorAll('.mdl-js-textfield');
428
  let isValid = true;
429
  
430
  textfields.forEach(field => {
431
    const textfield = field.MaterialTextfield;
432
    textfield.checkValidity();
433
    
434
    const input = field.querySelector('.mdl-textfield__input');
435
    if (!input.validity.valid) {
436
      isValid = false;
437
    }
438
  });
439
  
440
  const submitButton = document.querySelector('#submit-button').MaterialButton;
441
  if (isValid) {
442
    submitButton.enable();
443
  } else {
444
    submitButton.disable();
445
  }
446
  
447
  return isValid;
448
}
449

450
// Real-time validation
451
document.addEventListener('input', (event) => {
452
  if (event.target.matches('.mdl-textfield__input')) {
453
    const textfield = event.target.closest('.mdl-js-textfield').MaterialTextfield;
454
    textfield.checkValidity();
455
    textfield.checkDirty();
456
    validateForm();
457
  }
458
});
459
```
460

461
## Constants and Configuration
462

463
```javascript { .api }
464
// MaterialTextfield constants
465
interface TextfieldConstants {
466
  /** Value indicating no maximum rows limit */
467
  NO_MAX_ROWS: -1;
468
  /** Attribute name for maxrows configuration */
469
  MAX_ROWS_ATTRIBUTE: 'maxrows';
470
}
471

472
// MaterialCheckbox constants  
473
interface CheckboxConstants {
474
  /** Small timeout value for animation timing */
475
  TINY_TIMEOUT: 0.001;
476
}
477
```
478

479
## Error Handling
480

481
Form components may encounter various error conditions:
482

483
```javascript
484
// Handle component access errors
485
function safeComponentAccess(element, componentName) {
486
  try {
487
    const component = element[componentName];
488
    if (!component) {
489
      console.warn(`Component ${componentName} not found on element`);
490
      // Try to upgrade the element
491
      componentHandler.upgradeElement(element);
492
      return element[componentName];
493
    }
494
    return component;
495
  } catch (error) {
496
    console.error(`Error accessing ${componentName}:`, error);
497
    return null;
498
  }
499
}
500

501
// Validate input values
502
function safeSliderChange(slider, value) {
503
  const input = slider.element_.querySelector('input');
504
  const min = parseFloat(input.min) || 0;
505
  const max = parseFloat(input.max) || 100;
506
  
507
  if (value < min || value > max) {
508
    console.warn(`Slider value ${value} outside range [${min}, ${max}]`);
509
    value = Math.max(min, Math.min(max, value));
510
  }
511
  
512
  slider.change(value);
513
}
514
```