Runtime configuration
Table of contents
Polymer supports runtime options that are useful for debugging and toggling between native APIs and their polyfill counterparts.
Flags can be used in combination with each other and settable three different ways:
- as attributes on the
<script>
tag that loadswebcomponents.js
- as URL query parameter
- directly on the
Platform.flags
object before loadingwebcomponents.js
.
Debug flags
To use the debugging options, you must install and use the debug version of libraries:
- Install
polymer-dev
andplatform-dev
and then tweak the referencesbower install Polymer/platform-dev Polymer/polymer-dev
- Rewrite
webcomponentsjs/webcomponents.js
toplatform-dev/webcomponents.js
inindex.html
- Comment out line 12 and uncomment line 13 in polymer.html
- Install
platform-dev
andpolymer-dev
on top of the minified versionsbower install polymer=Polymer/polymer-dev platform=Polymer/platform-dev
debug
Example usage
URL param:
http://localhost/yourapp?debug
Attribute:
<script src="webcomponents.js" debug></script>
Setting Platform.flags
:
<script>
Platform = {flags: {debug: true}};
</script>
<script src="webcomponents.js"></script>
log
Controls console output.
Possible values:
Value | Description |
---|---|
bind | Setup actions performed by the data-binding engine. |
data | Runtime data transforms that result from bindings |
watch | Data change notifications |
events | Custom event bindings and event propagations |
ready | Custom element reaching a ready state |
Example usage
URL param:
http://localhost/yourapp?log=bind,ready
Attribute:
<script src="webcomponents.js" log="bind,ready"></script>
Setting Platform.flags
:
<script>
Platform = {flags: {log: 'bind,ready'}};
</script>
<script src="webcomponents.js"></script>
Configuration flags
register
Including register
forces the Custom Elements polyfill in browsers that support it natively.
Example usage
Attribute:
<script src="webcomponents.js" register></script>
URL param:
http://localhost/yourapp?register
Setting Platform.flags
:
<script>
Platform = {flags: {register: true}};
</script>
<script src="webcomponents.js"></script>
shadow
Selects a Shadow DOM implementation to use: native
for supported browsers or polyfill
for unsupported browsers. Note: if the browser supports Shadow DOM natively, the presence
of this parameter forces the native API.
Possible values:
Value | Description |
---|---|
native | Default. Use the native implementation of Shadow DOM if the browser supports. |
polyfill | Forces the Shadow DOM polyfill to be loaded using platform.poly.min.js . Default for browsers that do not support Shadow DOM natively. |
Example usage
Attribute:
<script src="webcomponents.js" debug shadow></script>
URL param:
http://localhost/yourapp?debug&shadow=polyfill
Setting Platform.flags
:
<script>
Platform = {flags: {shadow: 'polyfill'}};
</script>
<script src="webcomponents.js"></script>
Polyfill settings
Some of the polyfills support additional options to override their default behavior or toggle experimental features.
eager
Including eager
as a URL param or setting the CustomElements.flags.eager
flag
upgrades Custom Elements immediately instead of waiting for DOMContentsLoaded
time.
The Custom Elements polyfill defers upgrading elements until DOMContentsLoaded
time. It does this as a performance optimization. Subsequent to the initial page load, Mutation Observers are used to discover new elements. If a page is particularly complex, it can paint before custom elements have
had a chance to upgrade. Elements on the page will be displayed in their un-upgraded state, typically
resulting in FOUC. The eager
flag can help mitigate these potential FOUC issues.
Example usage
<script>
CustomElements = {flags: {eager: true}};
</script>
<script src="webcomponents.js"></script>
Or, equivalently:
http://localhost/yourapp?eager
Strict Shadow DOM styling
To instruct the Shadow DOM polyfill to enforce lower bound style encapsulation,
set Platform.ShadowCSS.strictStyling
.
Example usage
<script src="webcomponents.js"></script>
<script>
Platform.ShadowCSS.strictStyling = true;
</script>
Note: We’re setting strictStyling
after loading webcomponents.js
.
More information on this feature can be found in the Styling reference.