Tessl Tile for npm/html5shiv@3.7.0

or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

tessl/npm-html5shiv

JavaScript polyfill that enables HTML5 semantic elements to work in legacy Internet Explorer browsers

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/html5shiv@3.7.x

To install, run

npx @tessl/cli install tessl/npm-html5shiv@3.7.0

0
# HTML5 Shiv
1

2
HTML5 Shiv is a JavaScript polyfill that enables HTML5 semantic elements to work properly in legacy Internet Explorer browsers (IE6-9) and other older browsers. The library works by using JavaScript to create these HTML5 elements in the DOM before they are used, allowing CSS styling to be applied correctly.
3

4
## Package Information
5

6
- **Package Name**: html5shiv
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install html5shiv`
10

11
Alternative installations:
12
- **Bower**: `bower install html5shiv`
13
- **Direct download**: Available from GitHub releases
14

15
## Core Imports
16

17
Browser script tag (most common usage):
18

19
```html
20
<!--[if lt IE 9]>
21
<script src="node_modules/html5shiv/dist/html5shiv.js"></script>
22
<![endif]-->
23
```
24

25
For print support in IE6-8:
26

27
```html
28
<!--[if lt IE 9]>
29
<script src="node_modules/html5shiv/dist/html5shiv-printshiv.js"></script>
30
<![endif]-->
31
```
32

33
CommonJS/Node.js:
34

35
```javascript
36
const html5 = require('html5shiv');
37
```
38

39
AMD/RequireJS:
40

41
```javascript
42
require(['html5shiv'], function(html5) {
43
  // Use html5 object
44
});
45
```
46

47
## Architecture
48

49
HTML5 Shiv is built around several key components that work together to provide HTML5 element support in legacy browsers:
50

51
- **Feature Detection**: Automatically detects browser capabilities for HTML5 element support and CSS styling
52
- **Element Shiving**: Creates HTML5 elements in the DOM before they are used, ensuring proper recognition by CSS engines
53
- **Method Override Strategy**: Optionally overrides `document.createElement` and `document.createDocumentFragment` to provide transparent HTML5 element creation
54
- **CSS Injection**: Automatically injects basic display styles for HTML5 semantic elements (display: block for sectioning elements)
55
- **Print Support** (Print version only): Transforms HTML5 elements with namespace prefixes during print operations in IE6-8
56
- **Browser Compatibility Layer**: Provides graceful degradation for modern browsers while adding essential functionality for legacy browsers
57

58
The library follows a progressive enhancement approach - modern browsers with native HTML5 support receive minimal overhead, while legacy browsers get the full polyfill functionality.
59

60
## Basic Usage
61

62
**Automatic Setup (Recommended)**:
63
The library automatically initializes when loaded, detecting the browser environment and applying necessary HTML5 element support:
64

65
```html
66
<!DOCTYPE html>
67
<html>
68
<head>
69
  <!--[if lt IE 9]>
70
    <script src="dist/html5shiv.js"></script>
71
  <![endif]-->
72
</head>
73
<body>
74
  <header>
75
    <nav>
76
      <ul>
77
        <li><a href="#home">Home</a></li>
78
        <li><a href="#about">About</a></li>
79
      </ul>
80
    </nav>
81
  </header>
82
  <main>
83
    <article>
84
      <section>
85
        <h1>Article Title</h1>
86
        <p>Content goes here...</p>
87
      </section>
88
    </article>
89
  </main>
90
  <footer>
91
    <p>&copy; 2023 Company Name</p>
92
  </footer>
93
</body>
94
</html>
95
```
96

97
**Configuration Before Loading**:
98

99
```html
100
<script>
101
// Configure before loading the library
102
window.html5 = {
103
  'elements': 'mark section customelement',  // Custom element list
104
  'shivCSS': false,                          // Disable CSS injection
105
  'shivMethods': false                       // Disable method overriding
106
};
107
</script>
108
<!--[if lt IE 9]>
109
  <script src="dist/html5shiv.js"></script>  
110
<![endif]-->
111
```
112

113
**Programmatic Usage**:
114

115
```javascript
116
// After library is loaded, access the html5 object
117
console.log('HTML5 Shiv version:', html5.version);
118

119
// Manually shiv a document (usually not needed)
120
html5.shivDocument(document);
121

122
// Create HTML5 elements programmatically
123
var article = html5.createElement('article');
124
var section = html5.createElement('section');
125

126
// Add custom elements to the shiv list
127
html5.addElements('customelement anotherelement', document);
128
```
129

130
## Capabilities
131

132
### Document Shiving
133

134
Applies HTML5 element support and CSS styling to a document, enabling HTML5 semantic elements to work properly in legacy browsers.
135

136
```javascript { .api }
137
/**
138
 * Shivs the given document by applying HTML5 element support and CSS styling
139
 * @param ownerDocument - The document to shiv (optional, defaults to global document)
140
 * @returns The shived document
141
 */
142
function shivDocument(ownerDocument?: Document): Document;
143
```
144

145
### Element Creation
146

147
Creates HTML5 elements that work correctly in legacy browsers with proper styling and behavior.
148

149
```javascript { .api }
150
/**
151
 * Creates a shived HTML5 element that works in legacy browsers
152
 * @param nodeName - Name of the element to create (e.g., 'article', 'section')
153
 * @param ownerDocument - Context document (optional, defaults to global document)
154
 * @returns The created shived element
155
 */
156
function createElement(nodeName: string, ownerDocument?: Document): Element;
157
```
158

159
### Document Fragment Creation
160

161
Creates document fragments with HTML5 element support for efficient DOM manipulation.
162

163
```javascript { .api }
164
/**
165
 * Creates a shived document fragment with HTML5 element support
166
 * @param ownerDocument - Context document (optional, defaults to global document)
167
 * @returns The created shived document fragment
168
 */
169
function createDocumentFragment(ownerDocument?: Document): DocumentFragment;
170
```
171

172
### Element List Extension
173

174
Extends the built-in list of HTML5 elements that the library will shiv, useful for custom elements or newer HTML5 elements not in the default list.
175

176
```javascript { .api }
177
/**
178
 * Extends the built-in list of HTML5 elements and re-shivs the document
179
 * @param newElements - Whitespace-separated string or array of new element names to shiv
180
 * @param ownerDocument - Context document to re-shiv (optional)
181
 * @returns void
182
 */
183
function addElements(newElements: string | string[], ownerDocument?: Document): void;
184
```
185

186
### Print Support (Print Version Only)
187

188
Applies additional shiving for print scenarios in IE6-8 by wrapping HTML5 elements with printable equivalents.
189

190
```javascript { .api }
191
/**
192
 * Shivs the given document for print scenarios in IE6-8
193
 * Available only in html5shiv-printshiv.js version
194
 * @param ownerDocument - Document to shiv for printing (optional, defaults to global document)
195
 * @returns The shived document
196
 */
197
function shivPrint(ownerDocument?: Document): Document;
198
```
199

200
**Note**: This method is only available in the `html5shiv-printshiv.js` version and modifies the `type` property to include " print" (e.g., "default print").
201

202
## Configuration Properties
203

204
### Element List
205

206
Controls which HTML5 elements the library will shiv.
207

208
```javascript { .api }
209
/**
210
 * List of HTML5 element names to shiv
211
 * Can be set as a whitespace-separated string or array
212
 * Default: 'abbr article aside audio bdi canvas data datalist details dialog figcaption figure footer header hgroup main mark meter nav output picture progress section summary template time video'
213
 */
214
elements: string | string[];
215
```
216

217
### CSS Styling Control
218

219
Controls whether the library injects basic HTML5 CSS styling.
220

221
```javascript { .api }
222
/**
223
 * Flag to enable/disable HTML5 CSS styling injection
224
 * When true, adds display:block styles for HTML5 elements and basic mark styling
225
 * Default: true
226
 */
227
shivCSS: boolean;
228
```
229

230
### Method Override Control
231

232
Controls whether the library overrides createElement and createDocumentFragment methods.
233

234
```javascript { .api }
235
/**
236
 * Flag to enable/disable overriding of createElement and createDocumentFragment methods
237
 * When true, document methods are replaced with shived versions
238
 * Default: true
239
 */
240
shivMethods: boolean;
241
```
242

243
## Runtime Information
244

245
### Version Information
246

247
```javascript { .api }
248
/**
249
 * Current version of html5shiv library
250
 * Read-only property
251
 */
252
version: string; // '3.7.3'
253
```
254

255
### Browser Support Detection
256

257
```javascript { .api }
258
/**
259
 * Indicates if browser supports creating unknown/HTML5 elements natively
260
 * Automatically detected at runtime, read-only
261
 */
262
supportsUnknownElements: boolean;
263
```
264

265
### Library Type Identification
266

267
```javascript { .api }
268
/**
269
 * Describes the type of html5 object
270
 * 'default' for basic version, 'default print' for print version
271
 * Read-only property
272
 */
273
type: string;
274
```
275

276
## Types
277

278
```javascript { .api }
279
/**
280
 * Main html5shiv object exposed globally and via module exports
281
 */
282
interface HTML5Shiv {
283
  elements: string | string[];
284
  version: string;
285
  shivCSS: boolean;
286
  shivMethods: boolean; 
287
  supportsUnknownElements: boolean;
288
  type: string;
289
  shivDocument(ownerDocument?: Document): Document;
290
  createElement(nodeName: string, ownerDocument?: Document): Element;
291
  createDocumentFragment(ownerDocument?: Document): DocumentFragment;
292
  addElements(newElements: string | string[], ownerDocument?: Document): void;
293
  shivPrint?(ownerDocument?: Document): Document; // Only available in print version
294
}
295

296
/**
297
 * Configuration options that can be set before library initialization
298
 */
299
interface HTML5ShivOptions {
300
  elements?: string | string[];
301
  shivCSS?: boolean;
302
  shivMethods?: boolean;
303
}
304
```
305

306
## Browser Support
307

308
### Target Browsers
309
- **Internet Explorer 6-8**: Full functionality including CSS styling and method overrides
310
- **Internet Explorer 9**: CSS styling only (native element creation support)
311
- **Safari 4.x**: CSS styling for HTML5 elements
312
- **Firefox 3.x**: CSS styling for HTML5 elements
313
- **Modern browsers**: Automatic detection, minimal overhead (no-op when native support available)
314

315
### Print Support (Print Version Only)
316
The `html5shiv-printshiv.js` version provides additional functionality for proper printing of HTML5 elements in Internet Explorer 6-8:
317

318
- Wraps HTML5 elements with `html5shiv:` namespaced elements during printing
319
- Transforms CSS selectors to target namespaced elements
320
- Handles before/after print events automatically
321
- Requires IE-specific DOM methods (`applyElement`, `removeNode`, etc.)
322

323
## Error Handling
324

325
The library includes built-in error handling for various edge cases:
326

327
- **Feature detection failures**: Falls back to safe defaults if browser detection fails
328
- **Missing DOM methods**: Gracefully degrades when required DOM methods are unavailable
329
- **CSS injection errors**: Continues operation even if CSS injection fails
330
- **Element creation errors**: Provides fallback element creation when shiving fails
331

332
## Known Limitations
333

334
### Element Cloning Behavior
335
- HTML5 elements created via `createElement` may not clone properly in all IE versions
336
- Created elements have a parentNode instead of null (deviation from DOM specification)
337

338
### Print Version Requirements
339
- Print functionality requires Internet Explorer's proprietary DOM methods
340
- CSS transformation may not handle all edge cases perfectly
341
- May impact performance on complex sites with extensive print styles
342

343
### Method Overriding Side Effects
344
- Overridden `createElement` returns elements with non-standard parentNode behavior
345
- May conflict with other libraries that also override DOM methods (e.g., older jQuery versions)
346
- Can be disabled by setting `html5.shivMethods = false`
347

348
## Usage Examples
349

350
**Basic HTML5 Document Structure**:
351

352
```html
353
<!DOCTYPE html>
354
<html lang="en">
355
<head>
356
  <meta charset="utf-8">
357
  <title>My HTML5 Site</title>
358
  <!--[if lt IE 9]>
359
    <script src="html5shiv.js"></script>
360
  <![endif]-->
361
  <style>
362
    header, nav, main, article, section, aside, footer {
363
      display: block; /* Already handled by html5shiv CSS */
364
    }
365
  </style>
366
</head>
367
<body>
368
  <header>
369
    <h1>Site Title</h1>
370
    <nav>
371
      <ul>
372
        <li><a href="/">Home</a></li>
373
        <li><a href="/about">About</a></li>
374
      </ul>
375
    </nav>
376
  </header>
377
  
378
  <main>
379
    <article>
380
      <header>
381
        <h2>Article Title</h2>
382
        <time datetime="2023-01-15">January 15, 2023</time>
383
      </header>
384
      <section>
385
        <p>Article content goes here...</p>
386
      </section>
387
    </article>
388
    
389
    <aside>
390
      <section>
391
        <h3>Related Links</h3>
392
        <nav>
393
          <ul>
394
            <li><a href="/related1">Related Article 1</a></li>
395
            <li><a href="/related2">Related Article 2</a></li>
396
          </ul>
397
        </nav>
398
      </section>
399
    </aside>
400
  </main>
401
  
402
  <footer>
403
    <p>&copy; 2023 My Company</p>
404
  </footer>
405
</body>
406
</html>
407
```
408

409
**Custom Element Support**:
410

411
```html
412
<script>
413
// Add support for custom elements before loading html5shiv
414
window.html5 = {
415
  elements: 'abbr article aside audio canvas details figcaption figure footer header hgroup mark nav section summary time video my-custom-element another-element'
416
};
417
</script>
418
<!--[if lt IE 9]>
419
  <script src="html5shiv.js"></script>
420
<![endif]-->
421

422
<!-- Now you can use custom elements -->
423
<my-custom-element>
424
  <another-element>Custom content</another-element>
425
</my-custom-element>
426
```
427

428
**Dynamic Element Addition**:
429

430
```javascript
431
// Add new elements dynamically after library is loaded
432
html5.addElements(['dialog', 'details', 'summary'], document);
433

434
// Now these elements will work properly in IE
435
var dialog = document.createElement('dialog');
436
var details = document.createElement('details');
437
var summary = document.createElement('summary');
438
```