Update (2016-12-22): I am no longer supporting this library for all the reasons I address in my post The Dark Side of Polyfilling CSS. If you choose to use this library, please make sure you read the post, so you fully understand the challenges and limitations involved in writing CSS polyfills.

Introduction

Polyfill.js is a library designed to make writing CSS polyfills much, much easier. It's an abstraction library that takes care of the boilerplate, so you can focus on what your polyfill actually does.

For most CSS polyfills, the hardest part is not the polyfill logic itself, it's the boring stuff, the stuff that the browser is supposed to do for you: downloading the CSS, parsing it, and finding the parts you care about. If the CSS contains media queries, you need to deal with them, detect when they apply, and manually listen for changes.

Furthermore, on the Web today, most polyfills exist isolated from each other, which means they all repeat the same expensive tasks. Polyfill.js solves this problem. It provides a common API for Polyfill authors to hook in to, so all the hard work happens only once at most. The stylesheets are downloaded, parsed, and stored in a cache so additional requests don't do double work.

How It Works

Polyfill.js makes writing your own CSS Polyfill easy by breaking it down into the following three steps:

1) Include the Polyfill.js library on your page.

It doesn't really matter where you put it, as long as it appears after the stylesheet(s) containing the rules you want to polyfill.

<script src="path/to/polyfill.js"></script>

2) Create a new Polyfill Instance

You create a new instance of the Polyfill object by passing in one or more keywords representing the CSS features you want to polyfill. The keywords can be declaration keywords (property-value pairs) or selector keywords.

The following expression creates an instance to polyfill the :local-link CSS pseudo-class:

var localLinkPolyfill = Polyfill({ selectors: [":local-link"] })

3) Register Event Callbacks

Once you have your polyfill instance, you simply register two callbacks: doMatched() and undoUnmatched(). When the page first loads and Polyfill.js has done all its work behind the scenes, the doMatched() callback is invoked and is passed a list of CSS rules that contain the specified keywords and match the current media.

If the media values change (usually by resizing the browser window) and new rules match, the doMatched() callback will be invoked again, each time being passed the newly matched rules.

If the media value changes and some rules no longer match, the undoUnmatched() callback is invoked and passed a list of rules that previously matched but no longer do.

API

The Polyfill.js API consists of three public objects: Polyfill, Ruleset, and Rule. Only Polyfill is accessible in the global scope, the others are passed as arguments to callback functions.

The Polyfill Object

// create a polyfill for some CSS pseudo-classes
var p1 = Polyfill({
  exclude: ["third-party-css"],
  keywords: {
    selectors: [":local-link", ":nth-of-type"],
    declarations: ["*border-radius:*", "position:sticky", "display:*flex"]
  }
})

// create a polyfill for the flex display property
var p2 = Polyfill({
  include: ["flexbox", "box"],
  keywords: {
    declarations: ["display:*flex"]
  }
})

// create a polyfill by only passing keywords
var p3 = Polyfill({
  declarations: ["filter:*"]
})

polyfill.doMatched(function(rules) {
  // do somthing...
})

polyfill.undoUnmatched(function(rules) {
  // do somthing...
})

var matches = polyfill.getMatches()

polyfill.destroy()

The Ruleset Object

rules.each(function(rule) {
  // do something...
})

var rule = rules.at(0)

var length = rules.size()

The Rule Object

var selector = rule.getSelectors()

var declaration = rule.getDeclaration()

var media = rule.getMedia()

A Complete Example

Putting it all together, this is all the code you'd need to write a functioning polyfill for the new CSS property :local-link, which allows you to style links based on whether their href attribute points to a URL on the same domain (ok, there's a little more to it than that, but you get the idea).

Note: This example uses jQuery:

// First write a RegExp to match URL parts
var reURL = /^(?:(https?:)\/\/)?((?:[0-9a-z\.\-]+)(?::(?:\d+))?)/

// Then extend jQuery's selector engine to target local links
$.extend($.expr[':'], {
  "local-link": function(el) {
    var url = reURL.exec(el.href)
      , protocol = url[1]
      , host = url[2]
    return protocol == location.protocol && host == location.host
  }
})

// Create the polyfill and register the callbacks, that's it!
Polyfill({ selectors: [":local-link"] })
  .doMatched(function(rules) {
    rules.each(function(rule) {
      $(rule.getSelectors()).css(rule.getDeclaration())
    })
  })
  .undoUnmatched(function(rules) {
    rules.each(function(rule) {
      $(rule.getSelectors()).removeAttr("style")
    })
    localLinkPolyfill.getCurrentMatches().each(function(rule) {
      $(rule.getSelectors()).css(rule.getDeclaration())
    })
  })