Published: March 18, 2025
Polyfills have long been a part of the web developer experience, as they attempt to provide support for web features that aren't supported in all browsers. It would seem that polyfills are an indispensable tool in the web developer's toolkit, but it's nearly impossible to distill such a complex area of concern into a single, definitive statement.
Knowing when to use a polyfill for a feature depends on its availability across browsers, and Baseline can be helpful in making that determination. While Baseline doesn't tell you whether or not you should use polyfills, the clarity it brings to the availability of web platform features gives you an opportunity to be more selective, as excessive polyfills in an application can have significant drawbacks.
What are polyfills?
A polyfill is code that evaluates support for a feature in a browser, and—if the feature is unsupported—it will use JavaScript to attempt to provide that missing functionality.
An early example of a polyfill is Matchmedia.js, which used JavaScript to detect and provide support for the matchMedia method. matchMedia lets developers evaluate whether a media query matches the state of the current viewport in JavaScript. By loading a polyfill to provide the missing feature, it became possible to use the matchMedia method in any browser—but this polyfill is now no longer necessary, as matchMedia is available in nearly every browser in use.
While adding support for unsupported features is advantageous in some ways, the disadvantages of polyfills often go overlooked. As the number of polyfills increase in a web application, they can begin to have negative impacts.
What are the disadvantages of polyfills?
A feature that's polyfilled always has a cost compared to the same feature that's supported in a browser, and these costs add up as you add more polyfills:
- Polyfills are written in JavaScript, and any additional JavaScript in a web application can affect performance. Negative impacts can include render blocking, and blocking the main thread due to the additional long tasks that JavaScript can introduce through additional parsing and compiling work.
- Polyfills can also impact accessibility if they don't adhere to the specification of features they attempt to emulate. Some features modify the accessibility tree in ways that polyfills don't or can't.
- Compared to features implemented directly in browsers, polyfills may not have the ability to faithfully reproduce all aspects of the features they try to provide. This can lead to situations where the user experience is impacted in unexpected ways, or restricts how much of the feature is usable.
A good example of a polyfill that comes with some of these disadvantages is the container queries polyfill. Container queries let you apply CSS rules based on the state of an HTML element itself, as opposed to media queries, which let you apply CSS to elements based on the state of the viewport. This polyfill uses the ResizeObserver and MutationObserver JavaScript APIs to mimic the capabilities of container queries. In particular, ResizeObserver callbacks occur just before the browser draws a new frame, which increases presentation delay, an important consideration when optimizing a page's Interaction to Next Paint (INP).
Beyond performance, there are some aspects of container queries that a polyfill can't provide. While it's true that not every polyfill results in user experience problems or incomplete implementations of web features, the more of them you use, the more likely your application will be impacted in a negative way.
Where does Baseline come in?
It used to be difficult to evaluate whether a particular web feature was safe to use, even though data sources such as browser-compat-data have been used by various tools to help developers make these difficult decisions. Can I Use is a popular web feature support matrix that uses this data.
Baseline goes a step further by providing clear and consistent messaging about which web features are supported across all browsers through three status indicators:
- Limited availability: The feature is not supported across all major browsers.
- Newly available: The feature has emerged in all major browsers within the last 30 months.
- Widely available: The feature has been supported in all major browsers for more than the last 30 months.
Baseline does not consider polyfills as a part of its messaging. For example, if a feature has Limited availability, but is polyfillable for all browsers, that feature is never assumed to be either Newly or Widely available. The determining factor for whether a feature is Newly or Widely available is if a given feature is fully implemented in all major browsers. This communicates to developers which features are safe to use—and that informs developers on whether they should use a polyfill.
Determine your Baseline threshold
The main advantage of Baseline is that it reduces the number of things you need to worry about in your developer workflow. If you decide to adopt anything that has passed the Widely available line without worrying about polyfills, that means the only features you need to consider the status of are those outside of that line. Baseline can then help you decide what to do with Newly available features.
A feature becomes Newly available when supported by all target browsers, but that doesn't automatically mean that you can use the feature on day one and expect that every browser used by every user supports it. Most browsers now update themselves, but it takes time for all users to receive those updates. One factor to consider is when a device's browser version is tied to its operating system version. In these cases, there's a point at which a given user can no longer receive operating system updates until they replace their device.
Baseline features are grouped in yearly sets—for example, Baseline 2025, Baseline 2024, and so on—until enough time passes in which those features become part of the Widely available set. By coupling this information with information about your users, you can now make informed decisions about whether to use a Newly available feature, or use it with a polyfill.
The best data source for determining a Baseline threshold is the one for your website. Tools in this space are evolving to include data for Baseline thresholds. RUMvision is a product that provides this information.
In RUMvision's case, you can search not just for support of discrete features, but you can also see which percentage of users support a given Baseline feature set by year.
If you don't have RUM data for your site yet, RUM Insights gives you a broad view of the support of each Baseline feature set. One pattern you'll notice is that Baseline thresholds within the Widely available window are supported by 98% or more of all users, with the earliest thresholds achieving near 100% support by users.
How you determine feature support is your call, but generally speaking, the closer you get to 100% of users, the more confidence you can have that you can use Baseline web features without the need for a polyfill. As a general rule if 98% or 99% of users support a feature in their browser of choice, you can likely use the feature safely—but you still need to think about what that means for a minority of users.
When and when not polyfill a missing feature
The decision to use a polyfill is subjective, and it depends completely on your web application's requirements. However, knowing that there are potential user experience disadvantages to using them, you should strive to use as few of them as possible. Knowing whether a feature has reached Baseline Newly or Widely available should inform this decision.
Say you're looking to use a Baseline Newly available, but you have data that tells you that 95% of your users currently support the feature. This means that 5%—or one in every twenty users—will be using a browser that doesn't support the feature. This doesn't mean you should automatically reach for a polyfill, because whether you need a polyfill depends on the feature, and what the impact is if it's missing for a user.
While this can be a difficult call to make, it might help you to think about the potential negative user experience impacts that may result for users in browsers that don't support the feature you're looking to use, and whether those impacts warrant the use of a polyfill.
This evaluation criteria classifies features into three categories:
- Enhancement: The feature enhances the user experience in a way that doesn't result in visual changes or reduced functionality if it's unsupported. If the feature is missing for a user, they'll likely not notice. You very likely don't need to polyfill these features if they're missing.
- Additive: The feature provides an additive benefit that may impact how a web page looks or functions, but not in a way that surfaces serious problems. In fact, the user may not even notice unless they compare the same experience in a different browser that supports the feature. If a polyfill is available, lean towards not using it, especially if you're already polyfilling many other features, as adding additional polyfills will only worsen performance.
- Critical: The feature provides necessary functionality that, if missing in the user's browser, will result in a broken experience due to JavaScript evaluation and runtime errors, broken layouts, and other unacceptable outcomes. In this case, you decide to polyfill the feature, or avoid using it and figure out a different workaround.
It can be tricky to figure out which features fall into which category, but here are some practical examples:
- Good examples of enhancement features are those related to performance. Features such as
fetchpriority, HTTP/3 and others can improve the performance of a page. This is good for improving the user experience, but if the user uses a browser that doesn't support them, they won't experience adverse or even noticeable effects in many cases. Product stakeholders may be okay with the overwhelming majority of users gaining a benefit, so long as the vast minority are not left out in the cold. - Examples of additive features are those that enhance the visual appeal of a page. Color spaces and functions and subgrid are good examples of additive features that users may not notice if they're missing. In this case, some project stakeholders may have concerns about brand integrity if such functionality is missing for some users, but could be convinced that adoption of such features is okay if the experience is not utterly broken.
- Adoption of critical features are non-negotiable. One example of such a feature might be the HTML
<datalist>element, which if absent, could create a suboptimal user experience. Expect that project stakeholders won't accept adoption of features that will break the user experience in some browsers.
Generally speaking, here's how you can evaluate which feature falls into which category by its Baseline status:
- If a feature is Widely available you shouldn't reach for a polyfill—unless you have data about your users that explicitly tell you otherwise.
- If a feature is Newly available it has a very good likelihood of being supported broadly, but user support data should be used to determine which Baseline threshold is best to adhere to to minimize nuisances or unacceptable outcomes, with the understanding that support will improve to nearly 100% over time.
- If a feature is Limited availability it has the highest likelihood of creating a broken experience for some users, and therefore should be approached with caution, even if a polyfill is available.
Should I ever use Limited availability features?
The answer to this question is yes, but with some important caveats:
- Baseline features that have Limited availability are never guaranteed to become Newly available and beyond. You must very carefully consider what this means for the user experience.
- If you decide to adopt Limited availability features alongside polyfills, understand that you are passing on additional bytes to users unless you conditionally load those polyfills so that only those users who need them, get them. Even then, users who need them are still incurring a performance cost.
- Beyond the performance cost, users who require polyfills for Limited availability features may experience issues if a polyfill for a feature can't faithfully replicate the functionality of its natively implemented equivalent. This can impact functionality, and in some cases, even accessibility.
- Limited availability features are also subject to changes in their specified behavior. In particular, any feature only implemented in one browser may have to change when other browsers start to implement support. This means that your code, and any polyfill can fall out of sync with such changes.
Unless your users are locked to a single browser engine, using Baseline Newly and especially Widely available features is the recommended approach. Doing so means you will generally spend less time thinking about feature support, and more time using them, and spending the time you save on solving other problems.
Conclusion
The rules for whether or not you should use polyfills as you adopt web platform features aren't clear-cut. Like anything you do on the web, it requires careful thought while weighing benefits and risks. To review, a rough set of rules to approach the problem are:
- Understand that while polyfills are advantageous in some ways, they represent potential performance and accessibility costs, and may be unable to faithfully replicate unimplemented web features.
- Determine your Baseline threshold with data from your users, if possible. If that's not possible, the Baseline Widely available set of features is a good starting point, and consider using RUM insights data to make informed decisions.
- With that data, assess how many users could be impacted if their browser doesn't support features you're looking to use, and assess the severity of that impact.
- Communicate with project stakeholders to determine what features are acceptable and appropriate to use for your project's goals and business needs.
- If you must use Limited availability features, assess your audience and the risk for using them. Unless your users are locked to using a single browser engine, you can't guarantee compatibility, even with a polyfill.
These reasons are why polyfills are not included as a part of Baseline. The role of Baseline is to inform you of which features are supported in all major browser engines. You'll still need to know how many of your users can use Baseline features, and make decisions based on your users and the needs of your project. Baseline Widely available is a good default, and will often have the broadest web feature support for users in many cases.
The web platform is maturing in its capabilities faster than ever before, and there is a growing opportunity to use more of it as more features become interoperable and more broadly supported as time passes. This will provide you with more opportunities to use more web platform features with less polyfills.