DOCSEARCHbyAlgolia
Submit Docs

ie11-custom-properties

repository·master·Indexed 21 days ago

https://github.com/nuxodin/ie11customproperties

A CSS Custom Properties (CSS Variables) polyfill for Internet Explorer 11. It enables modern CSS variable syntax, including chaining, fallbacks, and dynamic updates, by rewriting CSS rules and using a class-based rendering system. The library supports JavaScript integration via setProperty and getPropertyValue, a subset of the CSS Houdini API through CSS.registerProperty, and provides a workaround for element-attribute styles via the ie-style attribute.

Tokens
1.4K
Snippets
4
Records
8
Agent score
26%

What's inside ie11-custom-properties

  1. Supported Features of the Polyfill

    master

    The polyfill provides comprehensive support for CSS Custom Properties in IE11, including:

    • CSS Syntax: Chaining (--bar:var(--foo)), fallbacks (var(--color, blue)), and support for inherit, initial, unset, and revert keywords.
    • Dynamic Content: Handles dynamically added HTML content, <style> elements, and <link> elements.
    • Selectors & Media: Supports :focus, :target, :hover, and media queries (triggering a redraw on change).
    • JavaScript Integration: Extends standard APIs to work with custom properties:
      • style.setProperty('--x','y')
      • style.getPropertyValue('--x')
      • getComputedStyle(el).getPropertyValue('--inherited')
    • Advanced APIs: Supports Houdini's CSS.registerProperty (though properties remain non-animatable).
    • Other: SVG support, cascade and inheritance support, and !important support on setters/getters.

  2. How the Polyfill Works

    master

    Since IE11 does not support properties starting with double dashes (--), the polyfill rewrites CSS rules to use a single-dash prefix (e.g., --foo becomes -ie-foo) which IE11 can process via the cascade.

    The process follows these steps:

    1. Rewriting: It transforms CSS rules. For example, li { color: var(--myColor); } becomes li { -ieHasVar-color: var(-ie-myColor); }.
    2. Detection: It uses a Mutation Observer to find affected elements when HTML or stylesheets change.
    3. Rendering: Each affected element is assigned a unique class (e.g., .iecp-u1) and its own specific style rule is generated to draw the computed property value directly onto that element.

  3. Install the IE11 Custom Properties Polyfill

    master

    To ensure the polyfill only loads in Internet Explorer 11 and not in modern browsers, include the following script snippet in the <head> of your HTML file. This uses a conditional check for document.documentMode to target IE11 specifically.

    <script>window.MSInputMethodContext && document.documentMode && document.write('<script src="https://cdn.jsdelivr.net/gh/nuxodin/ie11CustomProperties@4.1.0/ie11CustomProperties.min.js"><\/script>');</script>
    <script>window.MSInputMethodContext && document.documentMode && document.write('<script src="https://cdn.jsdelivr.net/gh/nuxodin/ie11CustomProperties@4.1.0/ie11CustomProperties.min.js"><\/script>');</script>

  4. Use ie11CustomProperties to polyfill CSS Variables in IE11

    master

    ie11CustomProperties.js is a polyfill that enables CSS Variable support in Internet Explorer 11. It works by rewriting CSS rules to use internal IE-compatible properties (prefixed with -ie-) and managing the application of these values via a MutationObserver and a drawing queue.

    To use it, include the script in your HTML. It automatically detects support and, if missing, begins polyfilling <style> tags and <link rel="stylesheet"> elements. It also provides a JS API for Houdini-style property registration.

    <!-- Include the polyfill in your HTML -->
<script src="path/to/ie11CustomProperties.js"></script>

  5. How the polyfill handles CSS Variable syntax

    master

    The polyfill uses a regex-based rewriting engine to transform standard CSS variable syntax into internal formats that IE11 can process:

    1. Setters: --variable: value is rewritten to -ie-variable: value. If !important is used, it becomes -ie-variable❗: value.
    2. Getters: var(--variable) is rewritten to include a special internal getter property -ieVar-variable. This allows the polyfill to track which properties need to be updated when a variable changes.

    This mechanism ensures that when a variable is updated via JavaScript (using setProperty('--var', 'value')), the polyfill can trigger a redraw of the affected elements.

  6. Limitations and Workarounds

    master

    Be aware of the following constraints when using the polyfill:

    • Styles in element-attributes: IE11 cannot retrieve raw content from standard style attributes for custom properties. Workaround: Use the ie-style attribute alongside the standard style attribute: <div style="--color:blue" ie-style="--color:blue">.
    • Specificity: Because the polyfill adds a unique class to elements (e.g., #header becomes #header.iecp_u44), the specificity of selectors containing var() is increased if the variables are not served from the :root.
    • @import: Variables defined within @import rules are currently not supported.
    • !important: There are known issues with !important usage.
    • External Stylesheets: To prevent the polyfill from processing a specific stylesheet, add the iecp-ignore tag to the <link> element.

  7. Apply CSS variables via the style attribute using ie-style

    master

    You can apply CSS variables directly to an element using the ie-style attribute. This allows you to define custom properties that the polyfill will parse and apply to the element's computed style.

    <!-- The polyfill will parse the content of ie-style and apply it to the element -->
<div ie-style="--main-bg: #ff0000; --text-size: 20px;">
  Content with custom properties
</div>

  8. Register CSS properties with CSS.registerProperty()

    master

    The polyfill implements a subset of the CSS Houdini API. You can use CSS.registerProperty(options) to define custom properties. This is useful for providing initialValue and inherits metadata, which the polyfill uses to better simulate CSS variable behavior in IE11.

    CSS.registerProperty({
  name: '--my-custom-color',
  syntax: '<color>',
  inherits: true,
  initialValue: '#ffffff'
});