0
# SVG for Everybody
1

2
SVG for Everybody is a JavaScript polyfill library that enables external SVG spritemap support across all browsers, including legacy versions of Internet Explorer, Safari, and Edge. It allows developers to use external SVG files with the `<use>` element by automatically detecting when external content is not natively supported and providing fallbacks through dynamic content injection or image replacements.
3

4
## Package Information
5

6
- **Package Name**: svg4everybody
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install svg4everybody`
10
- **CDN**: Include script directly from CDN or local files
11

12
## Core Imports
13

14
### ES Modules
15
```javascript
16
import svg4everybody from "svg4everybody";
17
```
18

19
### CommonJS
20
```javascript
21
const svg4everybody = require("svg4everybody");
22
```
23

24
### Global Script Tag
25
```html
26
<script src="/path/to/svg4everybody.js"></script>
27
<!-- svg4everybody is now available globally -->
28
```
29

30
### Legacy IE Support
31
```html
32
<script src="/path/to/svg4everybody.legacy.js"></script>
33
<!-- For IE 6-8 support with image fallbacks and additional options -->
34
```
35

36
**Standard vs Legacy Versions:**
37
- **Standard version** (`svg4everybody.js`): Supports modern browsers and IE 9+, includes `polyfill`, `validate`, and `attributeName` options
38
- **Legacy version** (`svg4everybody.legacy.js`): Supports IE 6-8 with image fallbacks, includes all standard options plus `fallback` and `nosvg` options
39

40
## Basic Usage
41

42
```javascript
43
// Basic usage - auto-detect browser needs and enable polyfill
44
svg4everybody();
45

46
// Call after DOM is ready or when new SVG elements are added
47
document.addEventListener('DOMContentLoaded', function() {
48
  svg4everybody();
49
});
50
```
51

52
### SVG Markup Usage
53
```html
54
<!-- External SVG spritemap -->
55
<svg role="img" title="CodePen">
56
  <use xlink:href="map.svg#codepen"/>
57
</svg>
58
<svg role="img" title="YouTube">
59
  <use xlink:href="map.svg#youtube"/>
60
</svg>
61
```
62

63
### SVG Spritemap Structure
64
```html
65
<!-- map.svg -->
66
<svg xmlns="http://www.w3.org/2000/svg">
67
  <symbol id="codepen" viewBox="0 0 64 64">
68
    <title>CodePen</title>
69
    <path d="..."/>
70
  </symbol>
71
  <symbol id="youtube" viewBox="0 0 64 64">
72
    <title>YouTube</title>
73
    <path d="..."/>
74
  </symbol>
75
</svg>
76
```
77

78
## Capabilities
79

80
### Main Polyfill Function
81

82
Initialize and run the SVG external content polyfill.
83

84
```javascript { .api }
85
/**
86
 * Main polyfill function that enables SVG external content support
87
 * @param rawopts - Optional configuration object
88
 */
89
function svg4everybody(rawopts?: SVGForEverybodyOptions): void;
90
```
91

92
### Configuration Options
93

94
```javascript { .api }
95
interface SVGForEverybodyOptions {
96
  /** Whether to activate the polyfill for external SVG content (auto-detected if not specified) */
97
  polyfill?: boolean;
98
  
99
  /** Custom validation function to determine which <use> elements to process */
100
  validate?: (src: string, svg: Element, use: Element) => boolean;
101
  
102
  /** Custom fallback function for generating image replacement URLs (LEGACY VERSION ONLY) */
103
  fallback?: (src: string, svg: Element, use: Element) => string;
104
  
105
  /** Forces image fallbacks instead of SVG (LEGACY VERSION ONLY, auto-detected for IE 6-8) */
106
  nosvg?: boolean;
107
  
108
  /** Alternative attribute name to check for SVG reference (in addition to xlink:href and href) */
109
  attributeName?: string;
110
}
111
```
112

113
## Advanced Usage Examples
114

115
### Custom Validation
116
```javascript
117
svg4everybody({
118
  validate: function(src, svg, use) {
119
    // Only process sprites from the /sprites/ directory
120
    return src.startsWith('/sprites/');
121
  }
122
});
123
```
124

125
### Custom Fallback (Legacy Version Only)
126
```javascript
127
// IMPORTANT: This requires svg4everybody.legacy.js, not the standard version
128
svg4everybody({
129
  fallback: function(src, svg, use) {
130
    // Custom fallback image logic
131
    return '/images/svg-fallback.png';
132
  }
133
});
134
```
135

136
### Force Image Fallbacks (Legacy Version Only)
137
```javascript
138
// IMPORTANT: This requires svg4everybody.legacy.js, not the standard version
139
svg4everybody({
140
  nosvg: true, // Force image fallbacks for all browsers
141
  fallback: function(src, svg, use) {
142
    // Convert map.svg#icon to map.svg.icon.png
143
    return src.replace(/\?[^#]+/, '').replace('#', '.').replace(/^\./, '') + '.png';
144
  }
145
});
146
```
147

148
### Manual Polyfill Control
149
```javascript
150
svg4everybody({
151
  polyfill: true // Force polyfill activation regardless of browser detection
152
});
153
```
154

155
### Alternative Attribute Name
156
```javascript
157
svg4everybody({
158
  attributeName: 'data-href' // Check data-href attribute in addition to xlink:href and href
159
});
160
```
161

162
## Browser Support
163

164
### Native Support
165
- Chrome 21+
166
- Firefox 4+
167
- Safari 7.1+
168
- Opera 23+
169
- iOS 8.1+
170
- Edge 13+
171

172
### Polyfilled Support
173
- Chrome 14-20
174
- Android Browser 4.1+
175
- iOS 6-7
176
- Safari 6
177
- Edge 12
178
- IE 9-11
179

180
### Legacy Support (with svg4everybody.legacy.js)
181
- IE 6-8 (with image fallbacks)
182

183
## Implementation Notes
184

185
### IE 6-8 Requirements
186
- Use `svg4everybody.legacy.js` instead of the standard version
187
- Include script in the `<head>` to properly shiv `<svg>` and `<use>` elements
188
- Set `X-UA-Compatible` to `ie=edge` for best results
189
- Use self-closing `<use/>` elements with trailing slash
190

191
### Accessibility Best Practices
192
```html
193
<!-- Use title attributes and ARIA roles -->
194
<svg role="img" title="Find me on Twitter">
195
  <use xlink:href="map.svg#twitter"/>
196
</svg>
197

198
<!-- For decorative icons -->
199
<svg role="presentation">
200
  <use xlink:href="map.svg#decorative-icon"/>
201
</svg>
202
```
203

204
### Default Fallback Behavior
205
By default, fallback images point to a PNG file in the same location as the SVG, with the `#` hash replaced by a `.` dot and appended with a `.png` extension:
206
- `map.svg#codepen` → `map.svg.codepen.png`
207
- `sprites.svg#icon` → `sprites.svg.icon.png`
208

209
## Types
210

211
```javascript { .api }
212
/** Configuration options for svg4everybody function */
213
interface SVGForEverybodyOptions {
214
  polyfill?: boolean;
215
  validate?: ValidationFunction;
216
  fallback?: FallbackFunction;
217
  nosvg?: boolean;
218
  attributeName?: string;
219
}
220

221
/** Validation function signature */
222
type ValidationFunction = (
223
  src: string,    // Current xlink:href or href attribute value
224
  svg: Element,   // Current SVG element
225
  use: Element    // Current USE element
226
) => boolean;     // Return true to process, false to skip
227

228
/** Fallback function signature (legacy version only) */
229
type FallbackFunction = (
230
  src: string,    // Current xlink:href or href attribute value
231
  svg: Element,   // Current SVG element  
232
  use: Element    // Current USE element
233
) => string;      // Return URL to fallback image
234
```