0
# Styling and Sizing
1

2
## Overview
3

4
@primer/octicons-react icons support comprehensive styling options through props and standard React/CSS approaches. All icons inherit styling capabilities from standard SVG elements while providing convenient abstractions for common use cases.
5

6
## Size Control
7

8
### Predefined Sizes
9

10
```typescript { .api }
11
type Size = 'small' | 'medium' | 'large'
12

13
interface SizeProps {
14
  /** Size as predefined string or custom pixel value */
15
  size?: number | Size
16
}
17
```
18

19
**Size Mappings:**
20
- `small`: 16px height by computed width
21
- `medium`: 32px height by computed width  
22
- `large`: 64px height by computed width
23

24
### Custom Numeric Sizes
25

26
```jsx
27
import { BeakerIcon } from '@primer/octicons-react'
28

29
function CustomSizes() {
30
  return (
31
    <div>
32
      <BeakerIcon size={12} />  {/* 12px height */}
33
      <BeakerIcon size={24} />  {/* 24px height */}
34
      <BeakerIcon size={48} />  {/* 48px height */}
35
      <BeakerIcon size={96} />  {/* 96px height */}
36
    </div>
37
  )
38
}
39
```
40

41
### Automatic Width Scaling
42
Icons automatically maintain their aspect ratio when height is specified. Width is computed based on the original icon proportions using the formula: `width = height * (naturalWidth / naturalHeight)` where natural dimensions come from the closest available SVG variant.
43

44
## Color Control
45

46
### Fill Property
47

48
```typescript { .api }
49
interface ColorProps {
50
  /** Fill color (defaults to 'currentColor') */
51
  fill?: string
52
}
53
```
54

55
**Default Behavior:**
56
Icons use `currentColor` by default, inheriting the text color from their parent element.
57

58
```jsx
59
import { AlertIcon, CheckIcon } from '@primer/octicons-react'
60

61
function ColorExamples() {
62
  return (
63
    <div style={{ color: 'blue' }}>
64
      {/* Uses parent's blue color */}
65
      <AlertIcon />
66
      
67
      {/* Explicit red color */}
68
      <CheckIcon fill="#ff0000" />
69
      
70
      {/* CSS color names */}
71
      <AlertIcon fill="green" />
72
      
73
      {/* CSS variables */}
74
      <CheckIcon fill="var(--primary-color)" />
75
    </div>
76
  )
77
}
78
```
79

80
## Vertical Alignment
81

82
### Alignment Options
83

84
```typescript { .api }
85
interface AlignmentProps {
86
  /** @deprecated use v-align utilities instead - Vertical alignment relative to text baseline */
87
  verticalAlign?: 'middle' | 'text-bottom' | 'text-top' | 'top' | 'unset'
88
}
89
```
90

91
**Alignment Values:**
92
- `text-bottom` (default): Aligns with text baseline
93
- `middle`: Centers with text middle
94
- `text-top`: Aligns with text top
95
- `top`: Aligns with element top
96
- `unset`: Removes alignment styling
97

98
```jsx
99
import { RepoIcon } from '@primer/octicons-react'
100

101
function AlignmentExamples() {
102
  return (
103
    <div>
104
      <h1>
105
        <RepoIcon verticalAlign="middle" /> Repository Name
106
      </h1>
107
      
108
      <p>
109
        <RepoIcon verticalAlign="text-bottom" /> Default alignment
110
      </p>
111
      
112
      <span>
113
        <RepoIcon verticalAlign="text-top" /> Top aligned
114
      </span>
115
    </div>
116
  )
117
}
118
```
119

120
## CSS Styling
121

122
### Class Names
123

124
```typescript { .api }
125
interface CSSProps {
126
  /** CSS class names */
127
  className?: string
128
  /** Inline styles */
129
  style?: React.CSSProperties
130
}
131
```
132

133
```jsx
134
import { GearIcon } from '@primer/octicons-react'
135

136
function StyledIcons() {
137
  return (
138
    <div>
139
      {/* CSS classes */}
140
      <GearIcon className="icon-primary rotating" />
141
      
142
      {/* Inline styles */}
143
      <GearIcon 
144
        style={{
145
          color: '#0969da',
146
          cursor: 'pointer',
147
          transition: 'transform 0.2s'
148
        }}
149
      />
150
    </div>
151
  )
152
}
153
```
154

155
### CSS-in-JS Integration
156

157
Icons work seamlessly with styled-components, emotion, and other CSS-in-JS libraries:
158

159
```jsx
160
import styled from 'styled-components'
161
import { SearchIcon } from '@primer/octicons-react'
162

163
const StyledIcon = styled(SearchIcon)`
164
  color: ${props => props.theme.primaryColor};
165
  cursor: pointer;
166
  transition: all 0.2s ease;
167
  
168
  &:hover {
169
    transform: scale(1.1);
170
    color: ${props => props.theme.hoverColor};
171
  }
172
`
173

174
function SearchButton() {
175
  return <StyledIcon size="medium" />
176
}
177
```
178

179
## Advanced Styling
180

181
### Responsive Sizing
182

183
```jsx
184
import { MenuIcon } from '@primer/octicons-react'
185

186
function ResponsiveIcon() {
187
  return (
188
    <MenuIcon 
189
      className="responsive-icon"
190
      style={{
191
        width: 'clamp(16px, 4vw, 32px)',
192
        height: 'auto'
193
      }}
194
    />
195
  )
196
}
197
```
198

199
### Animation Integration
200

201
```jsx
202
import { SyncIcon } from '@primer/octicons-react'
203

204
function SpinningIcon() {
205
  return (
206
    <SyncIcon 
207
      className="spinning"
208
      size="medium"
209
      style={{
210
        animation: 'spin 1s linear infinite'
211
      }}
212
    />
213
  )
214
}
215

216
// CSS
217
/*
218
@keyframes spin {
219
  from { transform: rotate(0deg); }
220
  to { transform: rotate(360deg); }
221
}
222
*/
223
```
224

225
### Theme Integration
226

227
Icons inherit CSS custom properties and work with design system tokens:
228

229
```jsx
230
import { StarIcon } from '@primer/octicons-react'
231

232
function ThemedIcon() {
233
  return (
234
    <StarIcon 
235
      fill="var(--color-icon-primary)"
236
      size="var(--size-icon-medium)"
237
      style={{
238
        marginRight: 'var(--spacing-xs)'
239
      }}
240
    />
241
  )
242
}
243
```
244

245
## Best Practices
246

247
### Performance Considerations
248
- Use predefined sizes when possible for consistent rendering
249
- Prefer `currentColor` for icons that should match text color
250
- Use CSS classes over inline styles for repeated styling patterns
251

252
### Accessibility
253
- Icons inherit accessibility props from their SVG implementation
254
- Color alone should not convey meaning - provide text alternatives
255
- Use appropriate contrast ratios for icon colors
256

257
### Responsive Design
258
- Test icon readability at different sizes
259
- Consider using different icon variants for mobile vs desktop
260
- Ensure touch targets meet minimum size requirements (44px+)
261

262
### Bundle Optimization
263
- Always import individual icons for tree-shaking benefits
264
- Consider icon sprite sheets for frequently used icons
265
- Use build-time optimizations for critical rendering paths