0
# @primer/octicons-react
1

2
## Overview
3

4
@primer/octicons-react is a React component library providing GitHub's Octicons as individual React components. It offers 339 scalable SVG icons with full TypeScript support, tree-shaking optimization, and comprehensive accessibility features. Each icon is available as a self-contained React component that renders clean SVG markup.
5

6
## Package Information
7

8
- **Name**: @primer/octicons-react  
9
- **Type**: React component library
10
- **Language**: JavaScript/TypeScript
11
- **Installation**: `npm install @primer/octicons-react`
12

13
## Core Imports
14

15
**ESM (ES Modules):**
16
```javascript { .api }
17
// Named imports (recommended for tree-shaking)
18
import { BeakerIcon, ZapIcon, AlertIcon } from '@primer/octicons-react'
19

20
// Import all icons (not recommended - large bundle)
21
import * as Octicons from '@primer/octicons-react'
22
```
23

24
**CommonJS:**
25
```javascript { .api }
26
// Named imports using destructuring
27
const { BeakerIcon, ZapIcon, AlertIcon } = require('@primer/octicons-react')
28

29
// Import all icons
30
const Octicons = require('@primer/octicons-react')
31
```
32

33
## Basic Usage
34

35
```jsx
36
import React from 'react'
37
import { BeakerIcon, ZapIcon } from '@primer/octicons-react'
38

39
export default function MyComponent() {
40
  return (
41
    <div>
42
      <BeakerIcon size="small" />
43
      <ZapIcon size="medium" fill="#ff0000" />
44
    </div>
45
  )
46
}
47
```
48

49
## Core Types
50

51
```typescript { .api }
52
interface OcticonProps extends React.ComponentPropsWithoutRef<'svg'> {
53
  /** Accessible label for screen readers */
54
  'aria-label'?: string
55
  /** References element that labels this icon */
56
  'aria-labelledby'?: string  
57
  /** Tab order for keyboard navigation (defaults to undefined) */
58
  tabIndex?: number
59
  /** Child elements (typically not used) */
60
  children?: React.ReactElement<any>
61
  /** CSS class names */
62
  className?: string
63
  /** Title text or element for tooltips */
64
  title?: string | React.ReactElement<any>
65
  /** Unique identifier */
66
  id?: string
67
  /** Fill color (defaults to 'currentColor') */
68
  fill?: string
69
  /** Icon data (for generic icon component) */
70
  icon?: Icon | React.ReactNode
71
  /** Size as number (pixels) or predefined size (defaults to 16) */
72
  size?: number | Size
73
  /** Vertical alignment relative to text (defaults to 'text-bottom') */
74
  /** @deprecated use v-align utilities instead */
75
  verticalAlign?: 'middle' | 'text-bottom' | 'text-top' | 'top' | 'unset'
76
}
77

78
type Size = 'small' | 'medium' | 'large'
79

80
type Icon = React.ForwardRefExoticComponent<OcticonProps & React.RefAttributes<SVGSVGElement>>
81
```
82

83
**Important Notes:**
84
- All icons support ref forwarding to the underlying SVG element
85
- Icons automatically apply CSS classes following the pattern `octicon octicon-{iconname}`
86
- SVG elements have `display="inline-block"` and `overflow="visible"` by default
87
- Icons automatically select the most appropriate SVG variant based on requested size
88
- Width is computed automatically based on original icon aspect ratio when height is specified
89

90
## Capabilities
91

92
### Icon Components
93
All 339 Octicon icons are available as individual React components with consistent props and behavior. Each icon follows the naming pattern `{IconName}Icon` and accepts the standard `OcticonProps` interface.
94

95
```typescript { .api }
96
// Example icon component signatures
97
function AlertIcon(props: OcticonProps): JSX.Element
98
function BeakerIcon(props: OcticonProps): JSX.Element  
99
function CheckIcon(props: OcticonProps): JSX.Element
100
```
101

102
**Icon Categories Available:**
103
- Interface & Navigation (arrows, chevrons, menus)
104
- Actions (plus, edit, delete, copy)
105
- Status & Alerts (check, alert, warning, error)
106
- Files & Folders (file, directory, code)
107
- Git & Version Control (branch, commit, merge, pull request)
108
- Communication (comment, discussion, mail)
109
- Media & Content (image, video, markdown)
110
- And many more...
111

112
[Complete Icon Reference](./icon-components.md)
113

114
### Sizing and Display
115
Icons support multiple sizing options and display customizations through props.
116

117
```typescript { .api }
118
// Size options
119
size: number | 'small' | 'medium' | 'large'
120

121
// Vertical alignment options (deprecated - use v-align utilities instead)
122
verticalAlign: 'middle' | 'text-bottom' | 'text-top' | 'top' | 'unset'
123
```
124

125
**Size Mappings:**
126
- `small`: 16px height by computed width
127
- `medium`: 32px height by computed width  
128
- `large`: 64px height by computed width
129
- Custom number: Exact pixel height with proportional width
130

131
[Detailed Styling Guide](./styling.md)
132

133
### Accessibility Features
134
Built-in accessibility support with ARIA attributes and proper semantic markup.
135

136
```typescript { .api }
137
// Accessibility props
138
'aria-label'?: string
139
'aria-labelledby'?: string
140
tabIndex?: number
141
title?: string | React.ReactElement<any>
142
```
143

144
[Accessibility Documentation](./accessibility.md)
145

146
### Customization
147
Icons can be styled using standard React props and CSS-in-JS approaches.
148

149
```typescript { .api }
150
// Styling props
151
fill?: string
152
className?: string
153
style?: React.CSSProperties
154
```
155

156
[Customization Guide](./customization.md)