css-vars-ponyfill

What is css-vars-ponyfill?

The css-vars-ponyfill package is a JavaScript library that provides a polyfill for CSS custom properties (CSS variables) in browsers that do not support them natively. It allows developers to use CSS variables in their stylesheets and ensures compatibility across all browsers, including older versions of Internet Explorer.

What are css-vars-ponyfill's main functionalities?

Basic Usage

This is the simplest way to use css-vars-ponyfill. By calling the cssVars() function, the library will automatically find and process all CSS variables in your stylesheets and apply the necessary polyfills to ensure compatibility.

cssVars();

Custom Configuration

This example demonstrates how to use css-vars-ponyfill with custom configuration options. You can specify various parameters such as the root element, whether to include shadow DOM, which elements to include or exclude, custom variables, and callback functions for different stages of the process.

cssVars({
  rootElement: document,
  shadowDOM: false,
  include: 'style,link[rel=stylesheet]',
  exclude: '',
  variables: {},
  onlyLegacy: true,
  preserveStatic: true,
  preserveVars: false,
  silent: false,
  updateDOM: true,
  updateURLs: true,
  watch: false,
  onBeforeSend: function(xhr, elm, url) {},
  onSuccess: function(cssText, elm, url) {},
  onWarning: function(message) {},
  onError: function(message, elm, xhr, url) {},
  onComplete: function(cssText, styleElms, cssVariables, benchmark) {}
});

Dynamic Updates

By setting the watch option to true, css-vars-ponyfill will automatically reprocess CSS variables whenever changes are detected in the DOM. This is useful for applications where styles are dynamically updated or added.

cssVars({
  watch: true
});

Other packages similar to css-vars-ponyfill

postcss-custom-properties

postcss-custom-properties is a PostCSS plugin that transforms W3C CSS Custom Properties (CSS variables) syntax into a static representation. Unlike css-vars-ponyfill, which works at runtime in the browser, postcss-custom-properties processes CSS at build time, making it suitable for build pipelines but not for dynamic updates.

README

css-vars-ponyfill

A ponyfill that provides client-side support for CSS custom properties (aka "CSS variables") in legacy and modern browsers.

• Documentation & Demos

Features

• Client-side transformation of CSS custom properties to static values
• Live updates of runtime values in both modern and legacy browsers
• Transforms <link>, <style>, and @import CSS
• Transforms relative url() paths to absolute URLs
• Supports chained and nested var() functions
• Supports var() function fallback values
• Supports web components / shadow DOM CSS
• Watch mode auto-updates on <link> and <style> changes
• UMD and ES6 module available
• TypeScript definitions included
• Lightweight (6k min+gzip) and dependency-free

Limitations

• Custom property declaration support is limited to :root and :host rulesets
• The use of var() is limited to property values (per W3C specification)
• CSS changes made using CSSOM APIs are not supported (see #19, #23, #77, #154).

Browser Support

Chrome 19+
Edge 12+
Firefox 6+
IE 9+
Safari 6+

Usage & Options

See the documentation site for details.

Sponsorship

A sponsorship is more than just a way to show appreciation for the open-source authors and projects we rely on; it can be the spark that ignites the next big idea, the inspiration to create something new, and the motivation to share so that others may benefit.

If you benefit from this project, please consider lending your support and encouraging future efforts by becoming a sponsor.

Thank you! 🙏🏻

Contact & Support

• Follow 👨🏻‍💻 @jhildenbiddle on Twitter and GitHub for announcements
• Create a 💬 GitHub issue for bug reports, feature requests, or questions
• Add a ⭐️ star on GitHub and 🐦 tweet to promote the project
• Become a 💖 sponsor to support the project and future efforts

License

This project is licensed under the MIT License. See the MIT LICENSE for details.

Copyright (c) John Hildenbiddle (@jhildenbiddle)

Changelog

2.4.9

2024-03-05

• Update GitHub workflow and badge