0
# Material Icons
1

2
Material Icons provides icon fonts and CSS for self-hosting Google's Material Design Icons, offering developers a comprehensive solution for incorporating Material Design iconography into web applications without relying on external CDNs. It includes multiple icon variants (filled, outlined, round, sharp, two-tone) in both font ligature and CSS class formats, with WOFF/WOFF2 font files for cross-browser compatibility and Sass variables for customization.
3

4
## Package Information
5

6
- **Package Name**: material-icons
7
- **Package Type**: npm
8
- **Language**: CSS/Sass with TypeScript definitions
9
- **Installation**: `npm install material-icons@latest`
10

11
## Core Imports
12

13
CSS import in JavaScript/TypeScript:
14

15
```typescript
16
import 'material-icons/iconfont/material-icons.css';
17
```
18

19
CSS import in stylesheets:
20

21
```css
22
@import 'material-icons/iconfont/material-icons.css';
23
```
24

25
Sass import:
26

27
```scss
28
@import 'material-icons/iconfont/material-icons.scss';
29
```
30

31
TypeScript definitions:
32

33
```typescript
34
import { MaterialIcon } from 'material-icons';
35
```
36

37
## Basic Usage
38

39
```html
40
<!-- Icon font ligatures (recommended) -->
41
<span class="material-icons">pie_chart</span>
42
<span class="material-icons-outlined">home</span>
43
<span class="material-icons-round">search</span>
44
<span class="material-icons-sharp">add</span>
45
<span class="material-icons-two-tone">settings</span>
46

47
<!-- CSS classes alternative -->
48
<span class="material-icons mi-pie-chart"></span>
49
<span class="material-icons-outlined mi-home"></span>
50

51
<!-- Angular Material integration -->
52
<mat-icon>pie_chart</mat-icon>
53
<mat-icon fontSet="material-icons-outlined">home</mat-icon>
54
<mat-icon fontIcon="mi-pie-chart"></mat-icon>
55
```
56

57
## Capabilities
58

59
### Icon Font CSS Classes
60

61
CSS classes for displaying Material Design Icons using font ligatures.
62

63
```css { .api }
64
/* Primary icon font classes */
65
.material-icons {
66
  font-family: "Material Icons";
67
  font-weight: normal;
68
  font-style: normal;
69
  font-size: 24px;
70
  line-height: 1;
71
  letter-spacing: normal;
72
  text-transform: none;
73
  display: inline-block;
74
  white-space: nowrap;
75
  word-wrap: normal;
76
  direction: ltr;
77
  -webkit-font-smoothing: antialiased;
78
  -moz-osx-font-smoothing: grayscale;
79
  text-rendering: optimizeLegibility;
80
  font-feature-settings: "liga";
81
}
82

83
.material-icons-outlined {
84
  font-family: "Material Icons Outlined";
85
  /* Same properties as above */
86
}
87

88
.material-icons-round {
89
  font-family: "Material Icons Round";
90
  /* Same properties as above */
91
}
92

93
.material-icons-sharp {
94
  font-family: "Material Icons Sharp";
95
  /* Same properties as above */
96
}
97

98
.material-icons-two-tone {
99
  font-family: "Material Icons Two Tone";
100
  /* Same properties as above */
101
}
102
```
103

104
**Usage Examples:**
105

106
```html
107
<!-- Display icons using font ligatures -->
108
<span class="material-icons">home</span>
109
<span class="material-icons">search</span>
110
<span class="material-icons">favorite</span>
111

112
<!-- Different variants -->
113
<span class="material-icons-outlined">settings</span>
114
<span class="material-icons-round">add_circle</span>
115
<span class="material-icons-sharp">delete</span>
116
<span class="material-icons-two-tone">account_circle</span>
117
```
118

119
### Individual Variant CSS Files
120

121
Optimized CSS files for specific icon variants to reduce bundle size.
122

123
```css { .api }
124
/* Available individual CSS files */
125
/* iconfont/filled.css - Filled icons only */
126
/* iconfont/outlined.css - Outlined icons only */
127
/* iconfont/round.css - Round icons only */
128
/* iconfont/sharp.css - Sharp icons only */
129
/* iconfont/two-tone.css - Two-tone icons only */
130
```
131

132
**Usage Examples:**
133

134
```typescript
135
// Import only needed variants to reduce bundle size
136
import 'material-icons/iconfont/filled.css';
137
import 'material-icons/iconfont/outlined.css';
138
// Instead of importing the full material-icons.css
139
```
140

141
### CSS Class Alternative
142

143
Alternative usage method with CSS classes instead of font ligatures, generating 2124 individual CSS classes.
144

145
```css { .api }
146
/* CSS class generation pattern */
147
/* Base pattern: .{$material-icons-css-prefix}-{icon-name-with-replacements} */
148
/* Default: underscore (_) replaced with dash (-) in icon names */
149

150
/* Generated classes for each icon variant */
151
.mi-123::before { content: "\eeaa"; }
152
.mi-360::before { content: "\e577"; }  
153
.mi-10k::before { content: "\e951"; }
154
.mi-pie-chart::before { content: "\e99a"; }
155
.mi-home::before { content: "\e88a"; }
156
.mi-search::before { content: "\e8b6"; }
157
.mi-account-circle::before { content: "\e853"; }
158
/* ... 2118+ more icon classes following same pattern */
159

160
/* Classes work with all font variants */
161
.material-icons .mi-{icon-name}::before { /* content for filled variant */ }
162
.material-icons-outlined .mi-{icon-name}::before { /* content for outlined variant */ }
163
.material-icons-round .mi-{icon-name}::before { /* content for round variant */ }
164
.material-icons-sharp .mi-{icon-name}::before { /* content for sharp variant */ }
165
.material-icons-two-tone .mi-{icon-name}::before { /* content for two-tone variant */ }
166
```
167

168
**Usage Examples:**
169

170
```html
171
<!-- Using CSS classes with different variants -->
172
<span class="material-icons mi-pie-chart"></span>
173
<span class="material-icons-outlined mi-home"></span>
174
<span class="material-icons-round mi-search"></span>
175
<span class="material-icons-sharp mi-account-circle"></span>
176
<span class="material-icons-two-tone mi-settings"></span>
177

178
<!-- Icons with underscores become dashes in CSS classes -->
179
<span class="material-icons mi-18-up-rating"></span>  <!-- icon: 18_up_rating -->
180
<span class="material-icons mi-account-circle"></span> <!-- icon: account_circle -->
181
```
182

183
```typescript
184
// Import CSS class styles (large file - 2124 classes)
185
import 'material-icons/css/material-icons.css';
186

187
// Or import minified version
188
import 'material-icons/css/material-icons.min.css';
189
```
190

191
### Sass Variables
192

193
Customizable Sass variables for font configuration.
194

195
```scss { .api }
196
/* iconfont Sass variables */
197
$material-icons-font-path: './' !default;
198
$material-icons-font-size: 24px !default;
199
$material-icons-font-display: block !default;
200

201
/* css Sass variables */
202
$material-icons-css-prefix: 'mi' !default;
203
$material-icons-css-search: '_' !default;
204
$material-icons-css-replace: '-' !default;
205
```
206

207
**Usage Examples:**
208

209
```scss
210
// Customize before importing
211
$material-icons-font-path: '~material-icons/iconfont/';
212
$material-icons-font-size: 18px;
213
@import 'material-icons/iconfont/material-icons.scss';
214

215
// Or for CSS classes approach
216
$material-icons-css-prefix: 'icon';
217
@import 'material-icons/css/material-icons.scss';
218
```
219

220
### Sass Mixins and Functions
221

222
Advanced Sass utilities for custom icon font implementation and CSS class generation.
223

224
```scss { .api }
225
/**
226
 * Creates a font-face declaration and CSS class for a Material Icon font variant
227
 * @param font-family - Font family name (e.g., 'Material Icons', 'Material Icons Outlined')
228
 */
229
@mixin material-icons-font($font-family);
230

231
/**
232
 * Applies base styling properties for Material Icon font classes
233
 * @param font-family - Font family name to apply
234
 */
235
@mixin material-icons-font-class($font-family);
236

237
/**
238
 * Generates CSS content for a specific icon using its codepoint
239
 * @param name - Icon name (e.g., 'home', 'search')
240
 * @param pseudo - Pseudo-element to target ('before' or 'after'), defaults to 'before'
241
 */
242
@mixin material-icon($name, $pseudo: 'before');
243

244
/**
245
 * String replacement utility function
246
 * @param string - Input string to process
247
 * @param search - String to search for
248
 * @param replace - Replacement string, defaults to empty string
249
 * @returns Modified string with replacements
250
 */
251
@function material-icons-str-replace($string, $search, $replace: '');
252

253
/**
254
 * Converts icon codepoint to CSS content value
255
 * @param codepoint - Unicode codepoint (e.g., 'e88a')
256
 * @returns Quoted CSS content string
257
 */
258
@function material-icons-content($codepoint);
259

260
/**
261
 * @deprecated As of v1.0, use '@extend .material-icons;' instead
262
 * Legacy mixin for Material Icons base styling
263
 */
264
@mixin material-icons();
265
```
266

267
**Usage Examples:**
268

269
```scss
270
// Create custom font variant
271
@include material-icons-font('Material Icons Custom');
272

273
// Apply base styling to custom class
274
.my-icon {
275
  @include material-icons-font-class('Material Icons');
276
}
277

278
// Create custom icon class with specific codepoint
279
.my-custom-home {
280
  @include material-icon('home');
281
}
282

283
// Use with ::after pseudo-element
284
.my-icon-after {
285
  @include material-icon('search', 'after');
286
}
287

288
// String manipulation
289
$cleaned-name: material-icons-str-replace('my_icon_name', '_', '-');
290
// Result: 'my-icon-name'
291
```
292

293
### TypeScript Definitions
294

295
Type definitions for icon names providing type safety.
296

297
```typescript { .api }
298
/**
299
 * Readonly tuple array containing all 2124 valid Material Design icon names
300
 */
301
type MaterialIcons = readonly [
302
  "123",
303
  "360", 
304
  "10k",
305
  "10mp",
306
  "11mp",
307
  "12mp",
308
  // ... (includes all 2124 icon names)
309
  "zoom_in",
310
  "zoom_in_map", 
311
  "zoom_out",
312
  "zoom_out_map"
313
];
314

315
/**
316
 * Union type of all valid Material Design icon names
317
 * Derived from MaterialIcons[number] for type safety
318
 */
319
type MaterialIcon = MaterialIcons[number];
320

321
export { MaterialIcon };
322
```
323

324
**Usage Examples:**
325

326
```typescript
327
import { MaterialIcon } from 'material-icons';
328

329
// Type-safe icon name usage
330
const iconName: MaterialIcon = 'home'; // ✓ Valid
331
const badIcon: MaterialIcon = 'invalid'; // ✗ TypeScript error
332

333
// In React components
334
interface IconProps {
335
  name: MaterialIcon;
336
}
337

338
function Icon({ name }: IconProps) {
339
  return <span className="material-icons">{name}</span>;
340
}
341
```
342

343
### Angular Material Integration
344

345
Specialized usage patterns for Angular Material's mat-icon component.
346

347
```html { .api }
348
<!-- mat-icon with ligatures -->
349
<mat-icon>icon_name</mat-icon>
350
<mat-icon fontSet="material-icons-outlined">icon_name</mat-icon>
351
<mat-icon fontSet="material-icons-round">icon_name</mat-icon>
352
<mat-icon fontSet="material-icons-sharp">icon_name</mat-icon>
353
<mat-icon fontSet="material-icons-two-tone">icon_name</mat-icon>
354

355
<!-- mat-icon with CSS classes -->
356
<mat-icon fontIcon="mi-icon-name"></mat-icon>
357
<mat-icon fontSet="material-icons-outlined" fontIcon="mi-icon-name"></mat-icon>
358
```
359

360
**Usage Examples:**
361

362
```html
363
<!-- Standard Angular Material usage -->
364
<mat-icon>home</mat-icon>
365
<mat-icon>search</mat-icon>
366
<mat-icon>settings</mat-icon>
367

368
<!-- With different variants -->
369
<mat-icon fontSet="material-icons-outlined">favorite</mat-icon>
370
<mat-icon fontSet="material-icons-round">add_circle</mat-icon>
371

372
<!-- With CSS classes -->
373
<mat-icon fontIcon="mi-pie-chart"></mat-icon>
374
```
375

376
## Available Icons
377

378
The package includes 2124 Material Design icons covering all standard categories:
379

380
- **Action Icons**: home, search, settings, favorite, delete, add, etc.
381
- **Navigation Icons**: arrow_back, arrow_forward, menu, close, etc.
382
- **Communication Icons**: email, phone, chat, message, etc.
383
- **Content Icons**: add, create, save, copy, cut, paste, etc.
384
- **Device Icons**: battery, wifi, bluetooth, camera, etc.
385
- **File Icons**: folder, insert_drive_file, cloud, backup, etc.
386
- **Hardware Icons**: keyboard, mouse, headset, etc.
387
- **Image Icons**: photo, image, crop, filter, etc.
388
- **Maps Icons**: place, directions, map, navigation, etc.
389
- **Social Icons**: person, group, public, share, etc.
390

391
Icon names use snake_case format for ligatures (e.g., `pie_chart`, `account_circle`) and kebab-case for CSS classes (e.g., `mi-pie-chart`, `mi-account-circle`).
392

393
## Types
394

395
```typescript { .api }
396
/**
397
 * Readonly tuple array containing all 2124 valid Material Design icon names
398
 */
399
type MaterialIcons = readonly [
400
  "123",
401
  "360", 
402
  "10k",
403
  "10mp",
404
  "11mp",
405
  "12mp",
406
  "13mp",
407
  "14mp",
408
  "15mp",
409
  "16mp",
410
  "17mp",
411
  "18_up_rating",
412
  "18mp",
413
  "19mp",
414
  "1k",
415
  "1k_plus",
416
  "1x_mobiledata",
417
  // ... (includes all 2124 icon names)
418
  "zoom_in",
419
  "zoom_in_map", 
420
  "zoom_out",
421
  "zoom_out_map"
422
];
423

424
/**
425
 * Union type of all valid Material Design icon names
426
 * Derived from MaterialIcons[number] for type safety
427
 */
428
type MaterialIcon = MaterialIcons[number];
429

430
export { MaterialIcon };
431
```