Polyfill: What It Is, How It Works, and Libraries for Emulating APIs

What Is Polyfill?

Polyfill is a piece of code (usually JavaScript) that implements functionality that the runtime environment does not support natively. The term was coined by Remy Sharp in 2009 as a play on words: Polyfill is analogous to Polyfilla, a filler that fills cracks in a wall. Polyfill fills the gaps between the standard and its support in a specific browser or runtime.

Polyfill does not modify existing code — it extends the runtime environment. If a browser does not support Array.prototype.includes, the polyfill adds this method to the Array prototype before the main code executes. Polyfills can emulate new global objects (Promise, Map, Set, Symbol), static methods (Array.from, Object.assign), and prototype methods.

Feature detection is a mandatory mechanism before installing a polyfill. Instead of checking the user-agent (which browser), you should check for the method's existence: if (!Array.prototype.includes) { Array.prototype.includes = ... }. This ensures that the polyfill does not overwrite the native implementation if it already exists. Google Analytics and other services collect API support data for analysis.

When Polyfills Emerged

The first polyfills appeared in the Internet Explorer 6–8 era (2005–2009), when developers discovered a gap between W3C standards and browser implementations. The term was introduced by Remy Sharp in 2009 at BarCamp London. The first mass polyfill was html5shiv (2009) — a library that adds support for HTML5 tags (<section>, <article>, <nav>) in Internet Explorer.

With the advent of ES6 (2015) and the annual ECMAScript release cycle, the number of required polyfills grew. Each year the standard adds new methods (Array.includes, String.padStart, Object.fromEntries, Promise.allSettled) that are not supported by older browsers. core-js, started as es6-shim in 2014, became a universal solution. As of 2026, core-js contains over 5,000 polyfill modules for ES5–ES2025.

What Can and Cannot Be Polyfilled

Polyfill vs Transpilation: Differences and Interaction

Transpilation converts new syntax into old syntax (const → var, () => {} → function() {}). Polyfill adds missing methods and objects (Promise, Array.includes). These two mechanisms complement each other: transpilation makes the code syntactically compatible, polyfills ensure API completeness. Babel + core-js is the standard combination for full support.

Babel @babel/preset-env with the useBuiltIns option determines which polyfills are needed based on target browsers. useBuiltIns: "usage" analyzes which APIs are used in the code and imports only the necessary polyfills from core-js. useBuiltIns: "entry" imports all polyfills for target browsers through a single core-js/stable import.

Example: Polyfill for Array.prototype.includes

// Checking for existence and adding a polyfill
if (typeof Array.prototype.includes !== "function") {
  Object.defineProperty(Array.prototype, "includes", {
    value: function(searchElement, fromIndex) {
      if (this == null) {
        throw new TypeError("Array.prototype.includes called on null or undefined");
      }
      var arr = Object(this);
      var len = arr.length >>> 0;
      if (len === 0) { return false; }
      var start = fromIndex | 0;
      var k = Math.max(start >= 0 ? start : len + start, 0);

      while (k < len) {
        if (arr[k] === searchElement) { return true; }
        k++;
      }
      return false;
    },
    writable: true,
    configurable: true,
  });
}

// Usage — now safe in any browser
const arr = [1, 2, 3, 4, 5];
console.log(arr.includes(3)); // true

Polyfill for Array.prototype.includes checks whether the method is defined on the Array prototype. If not, it creates the property via Object.defineProperty with flags writable: true, configurable: true. The implementation follows the ES2016 specification: null/undefined check, conversion to object, handling of negative fromIndex. After adding the polyfill, calling arr.includes(3) works in all browsers, including Internet Explorer 11.

core-js: The Standard Polyfill Library

core-js is the most comprehensive JavaScript polyfill library, supporting all TC39 stage-4 proposals (ECMAScript standard). core-js includes polyfills for Promise, Symbol, Map, Set, WeakMap, WeakSet, Array methods, String methods, Object methods, Number methods, Math methods, Reflect, globalThis, and all stage-4 proposals. The current version core-js 3.38+ covers ES5–ES2025.

core-js integrates with Babel through @babel/preset-env and the useBuiltIns option. Without this integration, developers would have to manually import each polyfill: import "core-js/stable/array/includes". @babel/preset-env automatically adds the necessary imports based on target browsers from .browserslistrc. This reduces bundle size — only the needed polyfills are included.

Example: Polyfill for fetch

Fetch API is one of the most commonly polyfilled Web APIs. Native fetch implementation is available in Chrome 42+ (2015), Safari 10.1+ (2017), Firefox 39+ (2015), but is absent in Internet Explorer and older WebViews. The whatwg-fetch polyfill emulates fetch via XMLHttpRequest. An alternative is to use isomorphic-fetch (a polyfill for Node.js and browser) or the universal axios library, which does not require polyfills.

// Loading fetch polyfill only for old browsers
if (typeof self.fetch !== "function") {
  import("whatwg-fetch").then(module => {
    self.fetch = module.fetch;
    console.log("fetch polyfill loaded");
  });
}

// Using fetch (works with both polyfill and native API)
async function loadData() {
  try {
    const response = await fetch("https://api.example.com/data");
    const json = await response.json();
    return json;
  } catch (error) {
    console.error("Failed to load:", error);
  }
}

Dynamic import of the fetch polyfill via import() ensures that modern browsers do not load unnecessary code. The polyfill loads asynchronously and does not block the main thread. After loading, self.fetch replaces the native implementation or adds the missing one. This is a progressive enhancement technique: modern browsers get only native code, older ones get the additional polyfill.

Integrating core-js with Babel

// babel.config.js — core-js + preset-env
module.exports = {
  presets: [
    ["@babel/preset-env", {
      useBuiltIns: "usage",
      corejs: {
        version: "3.38",
        proposals: true,
      },
      targets: {
        browsers: ["> 0.5%", "not dead", "not op_mini all"],
      },
    }],
  ],
};

# .browserslistrc — target browsers
> 0.5%
last 2 versions
not dead
not op_mini all
ie >= 11
not ios_saf < 12

useBuiltIns: "usage" analyzes the code and adds only the polyfills that are actually used. corejs.version specifies the core-js version in the project. targets.browsers defines the minimum browser level — the older the target browsers, the more polyfills will be included. .browserslistrc is used not only by Babel but also by Autoprefixer, PostCSS, and Stylelint for consistent targeting.

Polyfill.io and Dynamic Polyfill Loading

Polyfill.io is a service (and an eponymous library) that dynamically determines which polyfills the user's browser needs and returns only those. Polyfill.io uses the User-Agent header to determine the browser version and serves a minimal set of polyfills. This reduces the amount of data transferred compared to a universal polyfill bundle.

Connecting Polyfill.io is done via a <script> tag before the main application code. The service analyzes the User-Agent and returns a JavaScript file with polyfills only for that browser. Chrome will receive no polyfills, IE 11 will receive the full set. This is an optimal approach for performance: modern browsers do not load unnecessary code.

Connecting Polyfill.io

<!-- Polyfill.io: dynamic loading -->
<script src="https://cdn.polyfill.io/v3/polyfill.min.js?features=Promise%2CArray.prototype.includes%2CObject.assign%2Cfetch"></script>

<!-- Local Polyfill.io version -->
<script src="/js/polyfill.js"></script>
<script>
  // feature detection for fetch
  if (!self.fetch) {
    loadScript("/js/fetch-polyfill.js");
  }
</script>

The features parameter in the Polyfill.io URL specifies which polyfills to load. Possible values: method names (Array.prototype.includes), global objects (Promise), or flags (es6, es2016). The "default" flag loads a basic set for modern JavaScript. For production projects, it is recommended to host Polyfill.io on your own CDN or use a local version of the library for availability control.

Polyfills in Mobile Applications and WebView

WebView in mobile applications (Android WebView, WKWebView on iOS) is a special environment for polyfills. The WebView version depends on the OS version and the installed Chrome System WebView update (Android) or WKWebView from iOS Safari. In older versions of Android (4.4, 5.0), WebView is based on Chromium 30–37 — without support for fetch, Promise, IntersectionObserver.

React Native uses JavaScriptCore (iOS) or Hermes (Android) — these engines implement ES6+ differently. JavaScriptCore on iOS supports most ES6 features but may lack some stage-3 proposals. Hermes (used by default in React Native 0.70+) supports a limited set of the ES standard — polyfills are mandatory for it.

Checking WebView Support

// feature detection for WebView
const polyfills = [];

// Promise
if (typeof Promise === "undefined") {
  polyfills.push("Promise");
}

// Fetch API
if (typeof self.fetch === "undefined") {
  polyfills.push("fetch");
}

// IntersectionObserver (needed for lazy loading)
if (typeof IntersectionObserver === "undefined") {
  polyfills.push("IntersectionObserver");
}

// Dynamic polyfill loading
if (polyfills.length > 0) {
  const script = document.createElement("script");
  script.src = "https://cdn.polyfill.io/v3/polyfill.min.js"
    + "?features=" + polyfills.join(",");
  document.head.appendChild(script);
}

Feature detection for WebView checks for the presence of critical APIs (Promise, fetch, IntersectionObserver) and dynamically loads polyfills only for missing ones. This ensures that modern WebViews (Chrome 100+ on Android 12) do not load unnecessary code, while older WebViews (Android 5.0) get the required support.