0
# Primer Octicons
1

2
Primer Octicons is a comprehensive collection of 336 scalable SVG icons designed and maintained by GitHub as part of their Primer design system. The package provides programmatic access to icon data, SVG markup, and metadata, making it ideal for web applications, desktop applications, and any project requiring high-quality, consistent iconography with GitHub's design language.
3

4
## Package Information
5

6
- **Package Name**: @primer/octicons
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @primer/octicons`
10

11
## Core Imports
12

13
```javascript
14
const octicons = require("@primer/octicons");
15
```
16

17
For ES modules:
18

19
```javascript
20
import * as octicons from "@primer/octicons";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const octicons = require("@primer/octicons");
27

28
// Access an icon
29
const alertIcon = octicons.alert;
30

31
// Get basic icon information
32
console.log(alertIcon.symbol);    // "alert"
33
console.log(alertIcon.keywords);  // ["warning", "triangle", "exclamation", "point"]
34

35
// Generate SVG markup
36
const svg = alertIcon.toSVG();
37
console.log(svg); // <svg version="1.1" width="16" height="16"...>
38

39
// Generate SVG with custom options
40
const customSvg = alertIcon.toSVG({
41
  class: "my-icon warning-icon",
42
  "aria-label": "Warning message",
43
  width: 24
44
});
45
```
46

47
## Architecture
48

49
Primer Octicons provides a simple but powerful architecture:
50

51
- **Icon Objects**: Each icon is an object containing metadata and rendering capabilities
52
- **Lazy Loading**: Icon data is loaded from a generated JSON file containing all SVG paths and metadata
53
- **Size Selection**: Automatically chooses the best SVG size variant based on requested dimensions
54
- **Keyword System**: Each icon includes searchable keywords for discovery
55
- **CSS Integration**: Includes default CSS classes and supports custom styling
56

57
## Capabilities
58

59
### Icon Access and Properties
60

61
Access individual icons and their metadata through the main export object.
62

63
```javascript { .api }
64
// Main export - object containing all 336 icons
65
const octicons = {
66
  // Each icon is an object with the following properties:
67
  [iconName]: {
68
    /** The icon name (same as the object key) */
69
    symbol: string,
70
    /** Array of keywords/aliases for searchability */
71
    keywords: string[],
72
    /** Available size variants with SVG data */
73
    heights: {
74
      [height]: {
75
        /** Natural width of the SVG at this height */
76
        width: number,
77
        /** SVG path elements as HTML string */
78
        path: string,
79
        /** Default HTML attributes for the SVG element */
80
        options: {
81
          version: string,
82
          width: number,
83
          height: number,
84
          viewBox: string,
85
          class: string,
86
          "aria-hidden": string
87
        },
88
        /** Parsed SVG Abstract Syntax Tree */
89
        ast: {
90
          name: string,
91
          type: string,
92
          value: string,
93
          attributes: object,
94
          children: object[]
95
        }
96
      }
97
    },
98
    /** Generate complete SVG markup */
99
    toSVG: function(options)
100
  }
101
};
102
```
103

104
**Usage Examples:**
105

106
```javascript
107
// Access icon properties
108
const xIcon = octicons.x;
109
console.log(xIcon.symbol);    // "x"
110
console.log(xIcon.keywords);  // ["remove", "close", "delete"]
111

112
// Check available sizes
113
console.log(Object.keys(xIcon.heights)); // ["16", "24"]
114

115
// Get size-specific data
116
const size16 = xIcon.heights[16];
117
console.log(size16.width);    // 16
118
console.log(size16.path);     // "<path d=\"...\"></path>"
119

120
// Multi-word icon names require bracket notation
121
const arrowRight = octicons['arrow-right'];
122
// octicons.arrow-right would not work
123
```
124

125
### SVG Generation
126

127
Generate complete SVG markup with customizable options for styling and accessibility.
128

129
```javascript { .api }
130
/**
131
 * Generate complete SVG markup as a string
132
 * @param {object} [options] - Customization options for the SVG element
133
 * @param {string} [options.class] - Additional CSS classes to add to the SVG element
134
 * @param {string} [options.aria-label] - Accessibility label (removes aria-hidden, adds role="img")
135
 * @param {number} [options.width] - Custom width (height calculated proportionally)
136
 * @param {number} [options.height] - Custom height (width calculated proportionally)
137
 * @returns {string} Complete SVG element as HTML string
138
 */
139
toSVG(options);
140
```
141

142
**Usage Examples:**
143

144
```javascript
145
// Basic SVG generation (16px default)
146
const basicSvg = octicons.alert.toSVG();
147
// <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" 
148
//      class="octicon octicon-alert" aria-hidden="true">
149
//   <path d="..."></path>
150
// </svg>
151

152
// Custom CSS classes
153
const styledSvg = octicons.check.toSVG({ 
154
  class: "success-icon text-green" 
155
});
156
// Adds classes: "octicon octicon-check success-icon text-green"
157

158
// Accessibility support
159
const accessibleSvg = octicons.alert.toSVG({ 
160
  "aria-label": "Warning: Check your input" 
161
});
162
// Adds aria-label and role="img", removes aria-hidden
163

164
// Custom sizing (automatically selects best size variant)
165
const largeSvg = octicons.star.toSVG({ width: 32 });
166
// Uses 24px variant, scaled to 32px
167

168
// Size with both dimensions
169
const customSvg = octicons.repo.toSVG({ width: 20, height: 24 });
170
// Uses 24px variant with custom dimensions
171
```
172

173
### Size Selection and Scaling
174

175
Octicons automatically selects the most appropriate size variant based on requested dimensions.
176

177
**Size Selection Logic:**
178
- Default size: 16px height when no size specified
179
- Available sizes: Most icons have 16px and 24px variants, some icons may have additional sizes
180
- Selection algorithm: Finds the largest natural height that is less than or equal to the requested size, falling back to the first available size if none qualify
181
- Proportional scaling: When only width or height is specified, the other dimension is calculated proportionally based on the selected size variant's aspect ratio
182

183
**Usage Examples:**
184

185
```javascript
186
// Default size (16px)
187
octicons.x.toSVG(); // Uses 16px variant
188

189
// Request 20px height - uses 16px variant (largest ≤ 20)
190
octicons.x.toSVG({ height: 20 });
191

192
// Request 24px height - uses 24px variant (exact match)
193
octicons.x.toSVG({ height: 24 });
194

195
// Request 30px height - uses 24px variant (largest ≤ 30)
196
octicons.x.toSVG({ height: 30 });
197

198
// Request 12px height - uses 16px variant (no smaller variant available)
199
octicons.x.toSVG({ height: 12 });
200

201
// Width-based sizing (uses width or height, whichever is provided)
202
octicons.x.toSVG({ width: 48 }); // Selects variant based on width=48
203
```
204

205
## Available Icons
206

207
The package includes 336 icons across various categories:
208

209
### Navigation and Arrows
210
- `arrow-left`, `arrow-right`, `arrow-up`, `arrow-down`, `arrow-both`
211
- `arrow-small-left`, `arrow-small-right`, `arrow-small-up`, `arrow-small-down`
212
- `arrow-up-left`, `arrow-up-right`, `arrow-down-left`, `arrow-down-right`
213
- `chevron-left`, `chevron-right`, `chevron-up`, `chevron-down`
214

215
### Status and Alerts
216
- `alert`, `alert-fill`, `check`, `x`, `circle-slash`
217
- `stop`, `blocked`, `verified`, `unverified`
218

219
### User Interface
220
- `gear`, `three-bars`, `kebab-horizontal`, `apps`
221
- `home`, `search`, `bell`, `mail`
222
- `heart`, `star`, `bookmark`, `eye`
223

224
### Development and Git
225
- `code`, `terminal`, `repo`, `git-branch`
226
- `git-commit`, `git-merge`, `git-pull-request`
227
- `issue-opened`, `issue-closed`, `bug`
228

229
### Files and Folders
230
- `file`, `file-code`, `file-directory`, `folder`
231
- `archive`, `package`, `download`, `upload`
232

233
### Communication
234
- `comment`, `comment-discussion`, `mention`
235
- `people`, `person`, `organization`
236

237
### And many more categories including accessibility, AI/technology, time/calendar, security, and specialized GitHub features.
238

239
**Finding Icons:**
240

241
```javascript
242
// Get all available icon names
243
const allIcons = Object.keys(octicons);
244
console.log(`Total icons: ${allIcons.length}`); // 336
245

246
// Search by keywords
247
const alertIcons = allIcons.filter(name => 
248
  octicons[name].keywords.includes('warning')
249
);
250

251
// Icons with multi-word names use hyphens and bracket notation
252
const fileIcons = allIcons.filter(name => name.startsWith('file-'));
253
fileIcons.forEach(name => {
254
  const icon = octicons[name]; // Use bracket notation: octicons[name]
255
  console.log(`${name}: ${icon.keywords.join(', ')}`);
256
});
257
```
258

259
## CSS Styling
260

261
### Default Classes
262

263
All generated SVGs include these CSS classes:
264
- `octicon`: Base class for all Octicons
265
- `octicon-{icon-name}`: Specific class for each icon (e.g., `octicon-alert`)
266

267
### Recommended CSS
268

269
Include the package's CSS for consistent styling:
270

271
```css
272
/* From @primer/octicons/index.scss or build/build.css */
273
.octicon {
274
  display: inline-block;
275
  vertical-align: text-top;
276
  fill: currentColor;
277
  overflow: visible;
278
}
279
```
280

281
### Custom Styling
282

283
```javascript
284
// Add custom classes
285
const customIcon = octicons.star.toSVG({
286
  class: "favorite-icon text-yellow-500 hover:text-yellow-600"
287
});
288

289
// Icons inherit text color by default
290
// CSS: .text-blue { color: blue; }
291
// Result: blue icons
292
```
293

294
## Error Handling and Edge Cases
295

296
**Invalid Icon Names:**
297
```javascript
298
const invalid = octicons.nonexistent; // undefined
299
if (invalid) {
300
  // Safe to use
301
  const svg = invalid.toSVG();
302
}
303
```
304

305
**Multi-word Names:**
306
```javascript
307
// Correct - use bracket notation
308
const arrowRight = octicons['arrow-right'];
309

310
// Incorrect - will not work
311
// const arrowRight = octicons.arrow-right; // Syntax error
312
```
313

314
**Size Edge Cases:**
315
```javascript
316
// Very small sizes use smallest available variant
317
octicons.x.toSVG({ height: 1 }); // Uses 16px variant, scaled down
318

319
// Very large sizes use largest available variant  
320
octicons.x.toSVG({ height: 1000 }); // Uses 24px variant, scaled up
321

322
// Invalid options are ignored
323
octicons.x.toSVG({ invalidOption: true }); // Works normally
324
```
325

326
## Performance Considerations
327

328
- **Icon Data**: All 336 icons are loaded when the module is required
329
- **SVG Generation**: `toSVG()` is a lightweight operation that builds strings
330
- **Caching**: Consider caching generated SVG strings for repeated use
331
- **Size Selection**: Size selection algorithm runs on each `toSVG()` call
332

333
```javascript
334
// Cache frequently used SVGs
335
const alertSvg = octicons.alert.toSVG({ class: "warning" });
336
// Reuse alertSvg string instead of regenerating
337
```