or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-html5shiv

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/html5shiv@3.7.x

To install, run

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

index.mddocs/

HTML5 Shiv

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.

Package Information

  • Package Name: html5shiv
  • Package Type: npm
  • Language: JavaScript
  • Installation: 
    npm install html5shiv

Alternative installations:

  • Bower: 
    bower install html5shiv
  • Direct download: Available from GitHub releases

Core Imports

Browser script tag (most common usage):

<!--[if lt IE 9]>
<script src="node_modules/html5shiv/dist/html5shiv.js"></script>
<![endif]-->

For print support in IE6-8:

<!--[if lt IE 9]>
<script src="node_modules/html5shiv/dist/html5shiv-printshiv.js"></script>
<![endif]-->

CommonJS/Node.js:

const html5 = require('html5shiv');

AMD/RequireJS:

require(['html5shiv'], function(html5) {
  // Use html5 object
});

Architecture

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

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

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

Basic Usage

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

<!DOCTYPE html>
<html>
<head>
  <!--[if lt IE 9]>
    <script src="dist/html5shiv.js"></script>
  <![endif]-->
</head>
<body>
  <header>
    <nav>
      <ul>
        <li><a href="#home">Home</a></li>
        <li><a href="#about">About</a></li>
      </ul>
    </nav>
  </header>
  <main>
    <article>
      <section>
        <h1>Article Title</h1>
        <p>Content goes here...</p>
      </section>
    </article>
  </main>
  <footer>
    <p>&copy; 2023 Company Name</p>
  </footer>
</body>
</html>

Configuration Before Loading:

<script>
// Configure before loading the library
window.html5 = {
  'elements': 'mark section customelement',  // Custom element list
  'shivCSS': false,                          // Disable CSS injection
  'shivMethods': false                       // Disable method overriding
};
</script>
<!--[if lt IE 9]>
  <script src="dist/html5shiv.js"></script>  
<![endif]-->

Programmatic Usage:

// After library is loaded, access the html5 object
console.log('HTML5 Shiv version:', html5.version);

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

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

// Add custom elements to the shiv list
html5.addElements('customelement anotherelement', document);

Capabilities

Document Shiving

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

/**
 * Shivs the given document by applying HTML5 element support and CSS styling
 * @param ownerDocument - The document to shiv (optional, defaults to global document)
 * @returns The shived document
 */
function shivDocument(ownerDocument?: Document): Document;

Element Creation

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

/**
 * Creates a shived HTML5 element that works in legacy browsers
 * @param nodeName - Name of the element to create (e.g., 'article', 'section')
 * @param ownerDocument - Context document (optional, defaults to global document)
 * @returns The created shived element
 */
function createElement(nodeName: string, ownerDocument?: Document): Element;

Document Fragment Creation

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

/**
 * Creates a shived document fragment with HTML5 element support
 * @param ownerDocument - Context document (optional, defaults to global document)
 * @returns The created shived document fragment
 */
function createDocumentFragment(ownerDocument?: Document): DocumentFragment;

Element List Extension

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.

/**
 * Extends the built-in list of HTML5 elements and re-shivs the document
 * @param newElements - Whitespace-separated string or array of new element names to shiv
 * @param ownerDocument - Context document to re-shiv (optional)
 * @returns void
 */
function addElements(newElements: string | string[], ownerDocument?: Document): void;

Print Support (Print Version Only)

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

/**
 * Shivs the given document for print scenarios in IE6-8
 * Available only in html5shiv-printshiv.js version
 * @param ownerDocument - Document to shiv for printing (optional, defaults to global document)
 * @returns The shived document
 */
function shivPrint(ownerDocument?: Document): Document;

Note: This method is only available in the 

html5shiv-printshiv.js
version and modifies the 
type
property to include " print" (e.g., "default print").

Configuration Properties

Element List

Controls which HTML5 elements the library will shiv.

/**
 * List of HTML5 element names to shiv
 * Can be set as a whitespace-separated string or array
 * 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'
 */
elements: string | string[];

CSS Styling Control

Controls whether the library injects basic HTML5 CSS styling.

/**
 * Flag to enable/disable HTML5 CSS styling injection
 * When true, adds display:block styles for HTML5 elements and basic mark styling
 * Default: true
 */
shivCSS: boolean;

Method Override Control

Controls whether the library overrides createElement and createDocumentFragment methods.

/**
 * Flag to enable/disable overriding of createElement and createDocumentFragment methods
 * When true, document methods are replaced with shived versions
 * Default: true
 */
shivMethods: boolean;

Runtime Information

Version Information

/**
 * Current version of html5shiv library
 * Read-only property
 */
version: string; // '3.7.3'

Browser Support Detection

/**
 * Indicates if browser supports creating unknown/HTML5 elements natively
 * Automatically detected at runtime, read-only
 */
supportsUnknownElements: boolean;

Library Type Identification

/**
 * Describes the type of html5 object
 * 'default' for basic version, 'default print' for print version
 * Read-only property
 */
type: string;

Types

/**
 * Main html5shiv object exposed globally and via module exports
 */
interface HTML5Shiv {
  elements: string | string[];
  version: string;
  shivCSS: boolean;
  shivMethods: boolean; 
  supportsUnknownElements: boolean;
  type: string;
  shivDocument(ownerDocument?: Document): Document;
  createElement(nodeName: string, ownerDocument?: Document): Element;
  createDocumentFragment(ownerDocument?: Document): DocumentFragment;
  addElements(newElements: string | string[], ownerDocument?: Document): void;
  shivPrint?(ownerDocument?: Document): Document; // Only available in print version
}

/**
 * Configuration options that can be set before library initialization
 */
interface HTML5ShivOptions {
  elements?: string | string[];
  shivCSS?: boolean;
  shivMethods?: boolean;
}

Browser Support

Target Browsers

  • Internet Explorer 6-8: Full functionality including CSS styling and method overrides
  • Internet Explorer 9: CSS styling only (native element creation support)
  • Safari 4.x: CSS styling for HTML5 elements
  • Firefox 3.x: CSS styling for HTML5 elements
  • Modern browsers: Automatic detection, minimal overhead (no-op when native support available)

Print Support (Print Version Only)

The 

html5shiv-printshiv.js
version provides additional functionality for proper printing of HTML5 elements in Internet Explorer 6-8:

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

Error Handling

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

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

Known Limitations

Element Cloning Behavior

  • HTML5 elements created via 
    createElement
    may not clone properly in all IE versions
  • Created elements have a parentNode instead of null (deviation from DOM specification)

Print Version Requirements

  • Print functionality requires Internet Explorer's proprietary DOM methods
  • CSS transformation may not handle all edge cases perfectly
  • May impact performance on complex sites with extensive print styles

Method Overriding Side Effects

  • Overridden 
    createElement
    returns elements with non-standard parentNode behavior
  • May conflict with other libraries that also override DOM methods (e.g., older jQuery versions)
  • Can be disabled by setting 
    html5.shivMethods = false

Usage Examples

Basic HTML5 Document Structure:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>My HTML5 Site</title>
  <!--[if lt IE 9]>
    <script src="html5shiv.js"></script>
  <![endif]-->
  <style>
    header, nav, main, article, section, aside, footer {
      display: block; /* Already handled by html5shiv CSS */
    }
  </style>
</head>
<body>
  <header>
    <h1>Site Title</h1>
    <nav>
      <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/about">About</a></li>
      </ul>
    </nav>
  </header>
  
  <main>
    <article>
      <header>
        <h2>Article Title</h2>
        <time datetime="2023-01-15">January 15, 2023</time>
      </header>
      <section>
        <p>Article content goes here...</p>
      </section>
    </article>
    
    <aside>
      <section>
        <h3>Related Links</h3>
        <nav>
          <ul>
            <li><a href="/related1">Related Article 1</a></li>
            <li><a href="/related2">Related Article 2</a></li>
          </ul>
        </nav>
      </section>
    </aside>
  </main>
  
  <footer>
    <p>&copy; 2023 My Company</p>
  </footer>
</body>
</html>

Custom Element Support:

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

<!-- Now you can use custom elements -->
<my-custom-element>
  <another-element>Custom content</another-element>
</my-custom-element>

Dynamic Element Addition:

// Add new elements dynamically after library is loaded
html5.addElements(['dialog', 'details', 'summary'], document);

// Now these elements will work properly in IE
var dialog = document.createElement('dialog');
var details = document.createElement('details');
var summary = document.createElement('summary');