0
# @uifabric/icons
1

2
@uifabric/icons provides a comprehensive collection of 1800+ icons for Fluent UI React applications. It offers a centralized icon management system through the `initializeIcons` function that registers all icons and loads font resources from configurable CDN endpoints, with built-in support for custom base URLs and on-demand icon loading.
3

4
## Package Information
5

6
- **Package Name**: @uifabric/icons
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @uifabric/icons`
10

11
## Core Imports
12

13
```typescript
14
import { initializeIcons } from "@uifabric/icons";
15
```
16

17
For type-safe icon names:
18

19
```typescript
20
import { initializeIcons, IconNames, IconNamesInput } from "@uifabric/icons";
21
```
22

23
CommonJS:
24

25
```javascript
26
const { initializeIcons } = require("@uifabric/icons");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { initializeIcons } from "@uifabric/icons";
33
import { Icon } from "@fluentui/react/lib/Icon";
34

35
// Initialize with default Office CDN
36
initializeIcons();
37

38
// Use icons in React components
39
<Icon iconName="Mail" />
40
<Icon iconName="People" />
41
<Icon iconName="Settings" />
42
```
43

44
```typescript
45
import { initializeIcons } from "@uifabric/icons";
46
import { getIconClassName } from "@uifabric/styling";
47

48
// Initialize with custom CDN
49
initializeIcons("https://my.cdn.com/path/to/icons/");
50

51
// Use icons via CSS classes
52
const mailIcon = getIconClassName("Mail");
53
return `<i class="${mailIcon}" />`;
54
```
55

56
## Architecture
57

58
@uifabric/icons is built around several key components:
59

60
- **Icon Registration System**: Centralized icon registry that loads font definitions on demand
61
- **Font-Based Rendering**: Uses web fonts with Unicode mappings for optimal performance and scalability
62
- **CDN Flexibility**: Supports both Office CDN and custom CDN endpoints for font delivery
63
- **Modular Loading**: Icons are split across 19 font subset modules for optimized loading (1 primary + 18 numbered subsets)
64
- **Global Configuration**: Page-level configuration via `window.FabricConfig` to avoid race conditions
65
- **Icon Aliasing**: Built-in alias system for backwards compatibility and common naming variations
66

67
## Capabilities
68

69
### Icon Initialization
70

71
Core function that registers all available icons and configures font loading from CDN endpoints.
72

73
```typescript { .api }
74
/**
75
 * Initializes all Fluent UI icons by registering font subsets and configuring CDN endpoints
76
 * @param baseUrl - Base URL for icon font files (defaults to Office CDN or window.FabricConfig)
77
 * @param options - Optional icon configuration from @uifabric/styling
78
 */
79
function initializeIcons(
80
  baseUrl?: string,
81
  options?: IIconOptions
82
): void;
83

84
/**
85
 * Configuration options for icon initialization
86
 */
87
interface IIconOptions {
88
  /** Disable console warnings for missing icons */
89
  disableWarnings?: boolean;
90
  /** Enable warnings when icons are not found */
91
  warnOnMissingIcons?: boolean;
92
}
93
```
94

95
**Usage Examples:**
96

97
```typescript
98
import { initializeIcons } from "@uifabric/icons";
99

100
// Use default Office CDN
101
initializeIcons();
102

103
// Use custom CDN endpoint
104
initializeIcons("https://my.cdn.com/assets/icons/");
105

106
// With configuration options
107
initializeIcons(undefined, {
108
  disableWarnings: true,
109
  warnOnMissingIcons: false
110
});
111
```
112

113
### Global Configuration
114

115
Configure icon loading behavior before script initialization to avoid race conditions.
116

117
```typescript { .api }
118
declare global {
119
  interface Window {
120
    /**
121
     * Global configuration object for Fluent UI icon loading
122
     */
123
    FabricConfig?: {
124
      /**
125
       * Base URL for font files (legacy, use iconBaseUrl instead)
126
       */
127
      fontBaseUrl?: string;
128
      /**
129
       * Base URL for icon font files (preferred over fontBaseUrl)
130
       */
131
      iconBaseUrl?: string;
132
    };
133
  }
134
}
135
```
136

137
**Usage Examples:**
138

139
```html
140
<!-- Configure before loading scripts -->
141
<script>
142
  window.FabricConfig = {
143
    iconBaseUrl: "https://my.cdn.com/icons/"
144
  };
145
</script>
146
<script src="your-app-bundle.js"></script>
147
```
148

149
```typescript
150
// Check configuration at runtime
151
const win = getWindow();
152
const baseUrl = win?.FabricConfig?.iconBaseUrl || 
153
                win?.FabricConfig?.fontBaseUrl || 
154
                DEFAULT_BASE_URL;
155
```
156

157
### Icon Alias System
158

159
Built-in alias system for backwards compatibility and common naming variations.
160

161
```typescript { .api }
162
/**
163
 * Registers common icon aliases for backwards compatibility
164
 * Called automatically by initializeIcons()
165
 */
166
function registerIconAliases(): void;
167
```
168

169
**Available Icon Aliases:**
170

171
```typescript
172
// Common aliases registered by default
173
'trash' → 'delete'
174
'onedrive' → 'onedrivelogo'
175
'alertsolid12' → 'eventdatemissed12'
176
'sixpointstar' → '6pointstar'
177
'twelvepointstar' → '12pointstar'
178
'toggleon' → 'toggleleft'
179
'toggleoff' → 'toggleright'
180
```
181

182
**Usage Examples:**
183

184
```typescript
185
import { getIconClassName } from "@uifabric/styling";
186
import { initializeIcons } from "@uifabric/icons";
187

188
// Initialize icons (includes alias registration)
189
initializeIcons();
190

191
// Use aliases - these work the same as the target icons
192
const trashIcon = getIconClassName("trash");    // Same as "delete"
193
const toggleIcon = getIconClassName("toggleon"); // Same as "toggleleft"
194
```
195

196
### Icon Name Types
197

198
Type-safe icon naming system providing compile-time validation of icon names.
199

200
```typescript { .api }
201
/**
202
 * @deprecated Const enum use is deprecated. See GitHub issue #7110
203
 * Comprehensive enum containing all available icon names
204
 */
205
export const enum IconNames {
206
  PageLink = "PageLink",
207
  CommentSolid = "CommentSolid",
208
  ChangeEntitlements = "ChangeEntitlements",
209
  Installation = "Installation",
210
  ChevronDown = "ChevronDown",
211
  ChevronUp = "ChevronUp",
212
  Edit = "Edit",
213
  Add = "Add",
214
  Cancel = "Cancel",
215
  More = "More",
216
  Settings = "Settings",
217
  Mail = "Mail",
218
  People = "People",
219
  Phone = "Phone",
220
  Pin = "Pin",
221
  Shop = "Shop",
222
  // ... 1800+ more icon names
223
}
224

225
/**
226
 * Type representing valid icon name strings (union of all IconNames keys)
227
 * Use this type for parameters that accept icon names
228
 */
229
export type IconNamesInput = keyof typeof IconNames;
230
```
231

232
**Usage Examples:**
233

234
```typescript
235
import { IconNames, IconNamesInput } from "@uifabric/icons";
236
import { Icon } from "@fluentui/react/lib/Icon";
237

238
// Using enum (deprecated but available)
239
<Icon iconName={IconNames.Mail} />
240

241
// Using type-safe string parameter
242
function MyIconComponent({ iconName }: { iconName: IconNamesInput }) {
243
  return <Icon iconName={iconName} />;
244
}
245

246
// Type-safe function parameter
247
function createIconElement(name: IconNamesInput): string {
248
  return getIconClassName(name);
249
}
250
```
251

252
## Integration with Fluent UI
253

254
### React Icon Component
255

256
```typescript
257
import { Icon } from "@fluentui/react/lib/Icon";
258
import { initializeIcons } from "@uifabric/icons";
259

260
// Initialize icons first
261
initializeIcons();
262

263
// Use in components
264
function MyComponent() {
265
  return (
266
    <div>
267
      <Icon iconName="Mail" />
268
      <Icon iconName="People" />
269
      <Icon iconName="Settings" />
270
    </div>
271
  );
272
}
273
```
274

275
### CSS Class Generation
276

277
```typescript
278
import { getIconClassName } from "@uifabric/styling";
279
import { initializeIcons } from "@uifabric/icons";
280

281
// Initialize icons first
282
initializeIcons();
283

284
// Generate CSS classes for manual rendering
285
const mailClass = getIconClassName("Mail");
286
const settingsClass = getIconClassName("Settings");
287

288
// Use in HTML
289
return `
290
  <i class="${mailClass}" aria-label="Mail"></i>
291
  <i class="${settingsClass}" aria-label="Settings"></i>
292
`;
293
```
294

295
## Available Icons
296

297
The package includes 1800+ icons organized into categories:
298

299
**Common Icons:**
300
- Navigation: ChevronDown, ChevronUp, ChevronLeft, ChevronRight
301
- Actions: Add, Edit, Delete, Cancel, More, Settings
302
- Communication: Mail, Phone, People, Share
303
- Files: Folder, Upload, Download, Page
304
- UI Elements: Search, Filter, Sort, View, Clear
305

306
**Business Icons:**
307
- Office Apps: Word, Excel, PowerPoint, OneNote, Teams
308
- SharePoint: Lists, Libraries, Sites, Pages
309
- Productivity: Calendar, Tasks, Notes, Bookmarks
310

311
**Technical Icons:**
312
- Development: Code, Database, Server, Cloud
313
- System: Settings, Admin, Security, Permissions
314
- Status: Success, Warning, Error, Info
315

316
To see all available icons, explore the `IconNames` enum or refer to the [Fluent UI Icon Gallery](https://developer.microsoft.com/en-us/fluentui#/styles/web/icons).
317

318
## Font Loading Details
319

320
Icons are delivered through web fonts split into 19 optimized subsets:
321

322
- **Primary Font**: FabricMDL2Icons (fabric-icons.ts) - Core navigation and common icons
323
- **Subset Fonts**: FabricMDL2Icons-0 through FabricMDL2Icons-17 - Themed and specialized icons (18 additional subsets)
324
- **Format**: WOFF font format for broad browser support
325
- **Loading**: On-demand loading when icons are referenced
326
- **CDN**: Default Office CDN (https://res.cdn.office.net/files/fabric-cdn-prod_20241209.001/assets/icons/) with fallback support for custom endpoints
327

328
## Error Handling
329

330
The package handles common error scenarios:
331

332
```typescript
333
// Missing baseUrl - falls back to default CDN
334
initializeIcons(); // Uses Office CDN
335

336
// Invalid CDN URL - fonts may fail to load but won't crash
337
initializeIcons("https://invalid-cdn.com/");
338

339
// Missing icon names - handled by @uifabric/styling
340
const className = getIconClassName("NonExistentIcon"); // Returns fallback class
341
```
342

343
## Dependencies
344

345
Required peer dependencies from the Fluent UI ecosystem:
346

347
```typescript
348
// From @uifabric/styling
349
import { IIconOptions, IIconSubset, registerIcons, registerIconAlias } from "@uifabric/styling";
350

351
// From @uifabric/utilities  
352
import { getWindow } from "@uifabric/utilities";
353

354
// From @uifabric/set-version
355
import { setVersion } from "@uifabric/set-version";
356
```
357

358
These dependencies are automatically available when using @uifabric/icons in a Fluent UI React application.