0
# Material Design Lite
1
2
Material Design Lite (MDL) is a comprehensive JavaScript UI component library that implements Google's Material Design specification using vanilla CSS, JavaScript, and HTML. It enables developers to add Material Design styling and interactive components to static websites without requiring JavaScript frameworks or libraries, offering cross-device compatibility and graceful degradation for older browsers.
3
4
## Package Information
5
6
- **Package Name**: material-design-lite
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install material-design-lite`
10
- **CDN**: Include CSS and JS from Google's CDN
11
- **Version**: 1.3.0 (in limited support mode)
12
- **License**: Apache-2.0
13
14
## Core Imports
15
16
### Browser (CDN)
17
18
```html
19
<!-- CSS -->
20
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
21
<link rel="stylesheet" href="https://code.getmdl.io/1.3.0/material.indigo-pink.min.css">
22
23
<!-- JavaScript -->
24
<script defer src="https://code.getmdl.io/1.3.0/material.min.js"></script>
25
```
26
27
### Node.js
28
29
Material Design Lite is primarily designed for browser use. When used in Node.js environments (like server-side rendering), only the global componentHandler is available:
30
31
```javascript
32
// Access componentHandler in Node.js environment
33
require('material-design-lite');
34
// componentHandler is now available as a global
35
```
36
37
Note: Individual component classes (MaterialButton, MaterialTextfield, etc.) are not exported as CommonJS modules and are only available in browser environments after the library is loaded.
38
39
### Browser (Direct)
40
41
```html
42
<!-- Include built files -->
43
<link rel="stylesheet" href="path/to/material.min.css">
44
<script src="path/to/material.min.js"></script>
45
46
<!-- Access global componentHandler -->
47
<script>
48
// componentHandler is available globally
49
componentHandler.upgradeAllRegistered();
50
</script>
51
```
52
53
## Basic Usage
54
55
Material Design Lite works by applying CSS classes to HTML elements and then upgrading them with JavaScript functionality.
56
57
```html
58
<!DOCTYPE html>
59
<html>
60
<head>
61
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
62
<link rel="stylesheet" href="https://code.getmdl.io/1.3.0/material.indigo-pink.min.css">
63
</head>
64
<body>
65
<!-- Button with ripple effect -->
66
<button class="mdl-button mdl-js-button mdl-button--raised mdl-js-ripple-effect">
67
Click Me
68
</button>
69
70
<!-- Text field with floating label -->
71
<div class="mdl-textfield mdl-js-textfield mdl-textfield--floating-label">
72
<input class="mdl-textfield__input" type="text" id="sample3">
73
<label class="mdl-textfield__label" for="sample3">Text...</label>
74
</div>
75
76
<!-- Menu -->
77
<button id="demo-menu-lower-left"
78
class="mdl-button mdl-js-button mdl-button--icon">
79
<i class="material-icons">more_vert</i>
80
</button>
81
<ul class="mdl-menu mdl-menu--bottom-left mdl-js-menu mdl-js-ripple-effect"
82
for="demo-menu-lower-left">
83
<li class="mdl-menu__item">Some Action</li>
84
<li class="mdl-menu__item">Another Action</li>
85
</ul>
86
87
<script defer src="https://code.getmdl.io/1.3.0/material.min.js"></script>
88
</body>
89
</html>
90
```
91
92
## Architecture
93
94
Material Design Lite is built around several key architectural concepts:
95
96
- **Component Handler**: Central registry and lifecycle manager for all components
97
- **Widget vs Non-Widget Components**: Some components provide programmatic APIs, others are purely declarative
98
- **Automatic Upgrade**: Components are automatically initialized on page load
99
- **CSS-First Design**: Styling is primarily handled through CSS classes
100
- **Progressive Enhancement**: JavaScript adds interactivity to CSS-styled elements
101
- **Event-Driven**: Components communicate through DOM events
102
103
## Capabilities
104
105
### Component Management
106
107
Core system for managing component lifecycle, registration, and upgrades. Essential for dynamic content and programmatic control.
108
109
```javascript { .api }
110
interface ComponentHandler {
111
/** Upgrade all elements with MDL components in the DOM */
112
upgradeDom(optJsClass?: string, optCssClass?: string): void;
113
/** Upgrade a specific element with MDL components */
114
upgradeElement(element: Element, optJsClass?: string): void;
115
/** Upgrade a list of elements with MDL components */
116
upgradeElements(elements: Element[] | NodeList | HTMLCollection): void;
117
/** Upgrade all registered components in the DOM */
118
upgradeAllRegistered(): void;
119
/** Register a callback for component upgrades */
120
registerUpgradedCallback(jsClass: string, callback: (element: HTMLElement) => void): void;
121
/** Register a new component type */
122
register(config: ComponentConfigPublic): void;
123
/** Downgrade components on specified elements */
124
downgradeElements(nodes: Node[] | NodeList): void;
125
}
126
127
interface ComponentConfigPublic {
128
constructor: Function;
129
classAsString: string;
130
cssClass: string;
131
widget?: boolean;
132
}
133
```
134
135
[Component Management](./component-management.md)
136
137
### Form Components
138
139
Interactive form controls including buttons, text fields, checkboxes, radio buttons, switches, and sliders with Material Design styling and behavior.
140
141
```javascript { .api }
142
interface MaterialButton {
143
/** Disable the button */
144
disable(): void;
145
/** Enable the button */
146
enable(): void;
147
}
148
149
interface MaterialTextfield {
150
/** Check and update disabled state */
151
checkDisabled(): void;
152
/** Check and update focus state */
153
checkFocus(): void;
154
/** Check and update validity state */
155
checkValidity(): void;
156
/** Disable the textfield */
157
disable(): void;
158
/** Enable the textfield */
159
enable(): void;
160
/** Update textfield value */
161
change(value: string): void;
162
}
163
164
interface MaterialCheckbox {
165
/** Disable the checkbox */
166
disable(): void;
167
/** Enable the checkbox */
168
enable(): void;
169
/** Check the checkbox */
170
check(): void;
171
/** Uncheck the checkbox */
172
uncheck(): void;
173
}
174
```
175
176
[Form Components](./form-components.md)
177
178
### Layout Components
179
180
Structural components for application layout including headers, drawers, navigation, tabs, and responsive grid systems.
181
182
```javascript { .api }
183
interface MaterialLayout {
184
/** Toggle drawer open/closed state */
185
toggleDrawer(): void;
186
}
187
188
interface MaterialLayoutTab {
189
/** Programmatically select this tab */
190
show(): void;
191
}
192
```
193
194
[Layout Components](./layout-components.md)
195
196
### Navigation Components
197
198
Menu systems and navigation components including dropdown menus, tabs, and navigation drawers.
199
200
```javascript { .api }
201
interface MaterialMenu {
202
/** Display the menu */
203
show(evt?: Event): void;
204
/** Hide the menu */
205
hide(): void;
206
/** Toggle menu visibility */
207
toggle(evt?: Event): void;
208
}
209
```
210
211
[Navigation Components](./navigation-components.md)
212
213
### Feedback Components
214
215
User feedback components including progress indicators, spinners, snackbars, and tooltips for communicating system state and user actions.
216
217
```javascript { .api }
218
interface MaterialSnackbar {
219
/** Show snackbar with configuration */
220
showSnackbar(data: SnackbarData): void;
221
}
222
223
interface SnackbarData {
224
/** Text message to display */
225
message: string;
226
/** Optional action button text */
227
actionText?: string;
228
/** Optional action click handler */
229
actionHandler?: () => void;
230
/** Optional timeout in milliseconds (default: 2750) */
231
timeout?: number;
232
}
233
234
interface MaterialProgress {
235
/** Set progress value (0-100) */
236
setProgress(value: number): void;
237
/** Set buffer value (0-100) */
238
setBuffer(value: number): void;
239
}
240
```
241
242
[Feedback Components](./feedback-components.md)
243
244
### Data Display Components
245
246
Components for displaying structured data including data tables with sorting and selection capabilities.
247
248
```javascript { .api }
249
// MaterialDataTable provides automatic functionality for data tables
250
// No programmatic API - behavior is entirely declarative via HTML/CSS
251
```
252
253
[Data Display Components](./data-display-components.md)
254
255
### Visual Effects
256
257
Visual enhancement components including ripple effects and animations that provide tactile feedback and smooth transitions.
258
259
```javascript { .api }
260
interface MaterialRipple {
261
/** Get animation frame count */
262
getFrameCount(): number;
263
/** Set animation frame count */
264
setFrameCount(frameCount: number): void;
265
/** Get ripple element */
266
getRippleElement(): HTMLElement;
267
/** Set ripple coordinates */
268
setRippleXY(x: number, y: number): void;
269
/** Set ripple styling */
270
setRippleStyles(start: boolean): void;
271
/** Handle animation frames */
272
animFrameHandler(): void;
273
}
274
```
275
276
[Visual Effects](./visual-effects.md)
277
278
## Global Types
279
280
```javascript { .api }
281
// Events
282
interface MDLComponentUpgradingEvent extends CustomEvent {
283
type: 'mdl-componentupgrading';
284
bubbles: true;
285
cancelable: true;
286
}
287
288
interface MDLComponentUpgradedEvent extends CustomEvent {
289
type: 'mdl-componentupgraded';
290
bubbles: true;
291
cancelable: false;
292
}
293
294
interface MDLComponentDowngradedEvent extends CustomEvent {
295
type: 'mdl-componentdowngraded';
296
bubbles: true;
297
cancelable: false;
298
}
299
300
// Component Configuration
301
interface ComponentConfig {
302
constructor: Function;
303
className: string;
304
cssClass: string;
305
widget: boolean;
306
callbacks: Array<(element: HTMLElement) => void>;
307
}
308
309
// Component Instance
310
interface Component {
311
element_: HTMLElement;
312
className: string;
313
classAsString: string;
314
cssClass: string;
315
widget: string;
316
}
317
```
318
319
## Usage Patterns
320
321
### Component Access
322
323
**Widget Components** (widget: true):
324
```javascript
325
// Access component instance via element property
326
const button = document.querySelector('.mdl-js-button');
327
button.MaterialButton.disable();
328
329
const textfield = document.querySelector('.mdl-js-textfield');
330
textfield.MaterialTextfield.change('new value');
331
```
332
333
**Non-Widget Components** (widget: false):
334
```javascript
335
// No direct instance access - behavior is automatic
336
// Use componentHandler for lifecycle management only
337
componentHandler.upgradeElement(newElement);
338
```
339
340
### Dynamic Content
341
342
```javascript
343
// When adding MDL components dynamically
344
const newButton = document.createElement('button');
345
newButton.className = 'mdl-button mdl-js-button mdl-button--raised';
346
newButton.textContent = 'Dynamic Button';
347
document.body.appendChild(newButton);
348
349
// Upgrade the new element
350
componentHandler.upgradeElement(newButton);
351
352
// Or upgrade multiple elements
353
componentHandler.upgradeElements([newButton, anotherElement]);
354
```
355
356
### Error Handling
357
358
```javascript
359
try {
360
componentHandler.upgradeElement(invalidElement);
361
} catch (error) {
362
// Handle upgrade errors
363
console.error('Failed to upgrade element:', error);
364
}
365
366
// Listen for upgrade events
367
element.addEventListener('mdl-componentupgrading', (event) => {
368
// Cancel upgrade if needed
369
event.preventDefault();
370
});
371
```
372
373
## Browser Support
374
375
- **Required Features**: `classList`, `querySelector`, `addEventListener`, `Array.prototype.forEach`
376
- **Automatic Detection**: Adds `mdl-js` class to `<html>` when supported
377
- **Graceful Degradation**: Falls back to CSS-only styling in unsupported browsers
378
- **Supported Browsers**: Modern browsers (IE 11+, Chrome, Firefox, Safari, Edge)