diff --git a/app/3.0/docs/devguide/custom-css-properties.md b/app/3.0/docs/devguide/custom-css-properties.md index 765c56c9d2..2e9ec47335 100644 --- a/app/3.0/docs/devguide/custom-css-properties.md +++ b/app/3.0/docs/devguide/custom-css-properties.md @@ -4,355 +4,437 @@ title: Use custom properties -The author of a Polymer element can provide custom CSS properties that you can use to style the appearance of the element in your application. +Custom CSS properties allow you to define a CSS variable and use it in your styles. -Custom properties allow CSS authors to define cascading CSS variables, which are accepted by all CSS properties. +## Basic syntax for custom CSS properties -CSS variables can be used outside the context of custom elements, simply as a way to avoid scattering style data throughout a stylesheet. A CSS author assigns values to a custom property, and then uses the `var()` function to use these values elsewhere in the stylesheet. +To set the value of a custom CSS property: -This makes editing your CSS much easier and less prone to author error. +```css +element { + --custom-color: blue; +} +``` -For example, the [`` element](https://www.webcomponents.org/element/PolymerElements/paper-checkbox) provides custom properties for styling the colors, spacing and size of the checkbox and its label. +To use the custom CSS property to create a style: -As a developer, you can use these properties to style `` elements in your applications. +```css +element { + color: var(--custom-color); +} +``` -When you create your own custom elements, you can use custom properties to build an interface for the users of your element so they can style it. +You can use custom CSS properties outside of the context of custom elements, simply as a way to avoid scattering style data throughout a stylesheet. For example: -### Use a custom properties API to style an element +```html + + + + + +

Demonstrating basic use of custom properties

+ + +``` + +[See it on Plunker](http://plnkr.co/edit/AjZm3o?p=preview) -To use the interface of custom properties provided by an element author, look at the element's API documentation. +In the code sample above, the visual theme can be changed by editing the values of the custom properties. This makes it easier to create consistent themes, and your code will be less prone to error. -For a good example, visit the [`` API documentation](https://www.webcomponents.org/element/PolymerElements/paper-checkbox/paper-checkbox) +## Use the custom CSS properties provided by a Polymer element -This code sample inserts a `` element with its default styling: +The author of a Polymer element can provide custom CSS properties that you can use to style the appearance of the element in your application. This way, you don't need to know how the element's code works. -[See it on Plunker](http://plnkr.co/edit/if8IardvWBwZ2uMZIlgI?p=preview) +For example, suppose someone has authored two elements, `` and ``, which can be used together to create layouts in columns or rows, like so: ```html - - - - + + flex item 1 + flex item 2 + flex item 3 + +``` + +In the documentation for `flex-container`, you notice that the author has provided a custom CSS property, `--flex-direction`, to control whether the `flex-items` are laid out in a column or a row. You can assign your own value to `--flex-direction` in your app: -Check me +index.html { .caption} + +```html + + + + + + + + + + + + flex item 1 + + flex item n + + + ``` -Notice that: +[See it in Plunker](http://plnkr.co/edit/7eZqv8?p=preview) -* The checkbox label defaults to Times New Roman. This is true of any web page with no style info. -* The checkbox receives default colors from the paper-element theme. +**Custom CSS properties inherit.** In the code sample above, the value of `--flex-direction` is set in the `html` CSS rule. Since `flex-container` is a child of `html`, `flex-container` inherits this value. +{.alert} -The style properties of the `` element are configurable with the custom CSS properties that the element author has provided for us. +To find out about the custom CSS properties an element provides, see the element's documentation. -To use a custom property of a custom element, create a style rule using this syntax: +For examples of Polymer elements that provide extensive styling options with custom CSS properties, see the [API documentation for the `paper-ui-elements`](https://www.webcomponents.org/collection/PolymerElements/paper-ui-elements). + +## Provide custom CSS properties to users of your elements + +When you create Polymer elements, you can use custom CSS properties in your style rules. Users of your elements can then set values for the custom CSS properties, and control the appearance of your elements without needing to know how your code works. + +For example, suppose you are creating two elements, `` and ``, which can be used together to create layouts in columns or rows: ```html -paper-checkbox { - --paper-checkbox-checked-color: red; + + flex item 1 + flex item 2 + flex item 3 + +``` + +You can use a custom CSS property to control the flex direction of ``: + +flex-container.js (your code) { .caption } + +```js +/* ... */ +class FlexContainer extends PolymerElement { + static get template () { + return html` + + + `; + } } +/* ... */ ``` -[See it on Plunker](http://plnkr.co/edit/u41sHRHAWtYiYyjWnFlP?p=preview) +[See it in Plunker](http://plnkr.co/edit/7eZqv8?p=preview) -The paper elements provide a consistent way to configure styles across elements when using the paper element set, with variables. +Users can then assign their own value to `--flex-direction` like so: -We can use variables to configure the custom CSS properties in ``: +index.html (user's code) { .caption } ```html - +... ``` -## Create custom properties +If you provide documentation for the custom properties your element provides, users don't need to know any implementation details. See [Documenting your elements](/{{{polymer_version_dir}}}/docs/tools/documentation) for more information, or take a look at the [documentation for the Polymer `paper-ui-elements`](https://www.webcomponents.org/collection/PolymerElements/paper-ui-elements) for examples. -Rather than exposing the details of an element's internal implementation for -theming, an element author defines one or more custom CSS -properties as part of the element's API. +### Create default values for your CSS properties -These custom properties can be defined similarly to other standard CSS properties -and will inherit from the point of definition down the composed DOM tree, -similar to the effect of `color` and `font-family`. +You may want to provide default values for the CSS properties you use in your styles. -In the simple example below, the author of `` identified the need for -users of the toolbar to be able to change the color of the toolbar title. The -author exposed a custom property called `--my-toolbar-title-color` which is -assigned to the `color` property of the selector for the title element. Users -of the toolbar may define this variable in a CSS rule anywhere up the tree, and -the value of the property will inherit down to the toolbar where it is used if -defined, similar to other standard inheriting CSS properties. +To set a default value for a CSS property, use the following syntax: -Example: { .caption } +```css +div { + background-color: var(--theme-background, #e3f2fd); +} +``` -```html - - - - +To use a default value that is itself a custom property, use the following syntax: + +```css +div { + background-color: var(--theme-background, var(--default-light-blue)); +} ``` -Example usage of ``: { .caption } +## Inheritance and global styles + +Custom CSS properties inherit down the DOM hierarchy. In the code sample below, `` will inherit the custom properties defined for `div`, but not the custom properties defined for `span`. ```html - - - - + + + + + + + + + + + +
+ + flex item 1 + flex item 2 + flex item 3 + +
+ +

hello i am in a span

+ + + ``` -The `--my-toolbar-title-color` property only affects the color of the title -element encapsulated in ``'s internal implementation. In the -future the `` author can rename the `title` class or -restructure the internal details of `` without changing the custom -property exposed to users. +[See it on Plunker](http://plnkr.co/edit/mHpf7L?p=preview) -You can also include a default value in the `var()` function, to use in case the user -doesn't set the custom property: +You can use inheritance to define global custom CSS properties. In the code sample below, all nodes inherit the custom CSS properties defined for the top-level `html` element: -```css -color: var(--my-toolbar-title-color, blue); +index.html { .caption} + +```html +... + + + +... +
+ + flex item 1 + flex item 2 + flex item 3 + +
+ +

hello i am in a span

+ +... ``` -To include a default value that is a custom property, use this syntax: +[See it on Plunker](http://plnkr.co/edit/7rbXJY?p=preview) -```css -color: var(--my-color, var(--my-default-color)) -``` +Child elements that inherit global CSS properties can override them. For example, in the code sample above, `` inherited its custom CSS properties and fonts from the document-level styles for `html`. `` can override these properties: -Thus, custom CSS properties are a powerful way for element authors to -expose a theming API to their users in a way that naturally fits right alongside -normal CSS styling. +flex-item.js {.caption} -### Use custom CSS mixins +```js +static get template () { + return html` + + `; +} +``` -It may be tedious (or impossible) for an element author to predict every -CSS property that may be important for theming, let alone expose every -property individually. +[See it on Plunker](http://plnkr.co/edit/vlO7GV?p=preview) -CSS mixins are a proposal to fill this gap in functionality. To use CSS mixins, import the CSS mixins polyfill: +## Use custom CSS mixins -```html - - -``` +Using CSS mixins, you can define a set of CSS properties as a single custom property. -For backward compatibility, the `polymer.html` import includes the CSS mixins polyfill. No extra import is required when defining hybrid elements. +This is similar to defining a custom property with `var()`, but the value of the property is an object that defines one or more rules: -Using CSS mixins, an element author can define a set of CSS properties as a single custom property and then allow all properties in the set to be applied to a specific CSS rule -in an element's shadow DOM. The extension enables this with a mixin capability -that is analogous to `var`, but which allows an entire set of properties -to be mixed in. +```css +selector { + --mixin-name: { + /* rules */ + }; +} +``` Use `@apply` to apply a mixin: -
@apply --mixin-name;
+```css +selector { + @apply --mixin-name; +} +``` -Defining a mixin is just like defining a custom property, but the -value is an object that defines one or more rules: +Suppose we have two custom elements, `` and ``, which can be used together to create row or column layouts. -
selector {
-  --mixin-name: {
-    /* rules */
-  };
-}
+The author of the two elements uses a CSS mixin to apply theming information to both elements: -Example: { .caption } +flex-container.js {.caption} -```html - - - ... - + ... + `; +} ``` -Example usage of `my-toolbar`: { .caption } +flex-item.js { .caption} -```html - - - - + ... + `; +} ``` -## Use CSS inheritance +[See it on Plunker](http://plnkr.co/edit/glgUKv?p=preview) + +Users of `flex-item` can set values for the properties in the mixin: -If an element doesn't override styling information, that element inherits styles from its parent: +index.html {.caption} ```html - + + - - -

Check me

- ``` -## Create global styles - -Create global styles by styling the the html element of your document: +Note that any element using the `@apply` syntax must import the `@apply` polyfill: -```html - - - - +```js +// import CSS mixins polyfill +import '@webcomponents/shadycss/entrypoints/apply-shim.js'; ``` -Note that the font family is inherited, but the text color is not. This is because `` overrides the text color. +[See it in Plunker](http://plnkr.co/edit/glgUKv?p=preview) ### Custom property API for Polymer elements {#style-api} Polymer's custom property shim evaluates and applies custom property values once -at element creation time. In order to have an element (and its subtree) re- +at element creation time. In order to have an element (and its subtree) re- evaluate custom property values due to dynamic changes such as application of -CSS classes, call the [`updateStyles`](/2.0/docs/api/elements/Polymer.Element#method-updateStyles) +CSS classes, call the [`updateStyles`](/3.0/docs/api/elements/Polymer.Element#method-updateStyles) method on the element. To update _all_ elements on the page, you can also call `Polymer.updateStyles`. `updateStyles` can take a object with property/value pairs to update the current values of custom properties. -Example: { .caption } +Example { .caption } -```html - - - - -``` - -```html -this.updateStyles({ - '--some-custom-style': 'green', - '--another-custom-style': 'blue' -}); + } + static template get (){ + return html` + + My awesome app + + `; + } +} +customElements.define('x-custom', XCustom); ``` Occasionally an element needs to get the value of a custom property at runtime. This is handled @@ -367,15 +449,14 @@ if (ShadyCSS) { ``` Elements using the legacy API can use the -[`getComputedStyleValue`](/2.0/docs/api/mixins/Polymer.LegacyElementMixin#method-getComputedStyleValue) +[`getComputedStyleValue`](/3.0/docs/api/mixins/Polymer.LegacyElementMixin#method-getComputedStyleValue) instance method instead of testing for `ShadyCSS`. - ### Custom properties shim limitations Cross-platform support for custom properties is provided in Polymer by a JavaScript library that **approximates** the capabilities of the CSS Variables -specification *for the specific use case of theming custom elements*, while +specification *for the specific use case of theming custom elements*, while also extending it to add the capability to mixin property sets to rules as described above. For performance reasons, Polymer **does not attempt to replicate all aspects of native custom properties.** @@ -396,7 +477,7 @@ styles. For example, given this markup inside an element: -HTML: { .caption } +HTML { .caption } ```html
@@ -404,7 +485,7 @@ HTML: { .caption }
``` -CSS: { .caption } +CSS { .caption } ```css /* applies */ @@ -444,42 +525,37 @@ have the desired effect, since the dynamism is related to *application* of a cus Unlike normal CSS inheritance which flows from parent to child, custom properties in Polymer's shim can only change when inherited by a custom element from rules that set properties in scope(s) above it, or in a `:host` rule for -that scope. **Within a given element's local DOM scope, a custom property can -only have a single value.** Calculating property changes within a scope would be +that scope. **Within a given element's local DOM scope, a custom property can +only have a single value.** Calculating property changes within a scope would be prohibitively expensive for the shim and is not required to achieve cross-scope styling for custom elements, which is the primary goal of the shim. -```html - - - - + .container { + /* Setting the custom property here will not change */ + /* the value of the property for other elements in */ + /* this scope. */ + --custom-color: blue; + } + .child { + /* This will be always be red. */ + color: var(--custom-color); + } + +
+
I will be red
+
+ `; + } + customElements.define('my-element', MyElement); +} ``` #### Styling distributed elements not supported diff --git a/app/3.0/docs/devguide/shadow-dom.md b/app/3.0/docs/devguide/shadow-dom.md index 6c0b8b5c79..6f20ae49c5 100644 --- a/app/3.0/docs/devguide/shadow-dom.md +++ b/app/3.0/docs/devguide/shadow-dom.md @@ -4,7 +4,7 @@ title: Shadow DOM concepts -Shadow DOM is a new DOM feature that helps you build components. You can think of shadow DOM as a +Shadow DOM is a DOM feature that helps you build components. You can think of shadow DOM as a **scoped subtree** inside your element. **Read more on Web Fundamentals**. This document gives an overview of shadow DOM as it relates to @@ -61,19 +61,30 @@ When you provide a DOM template for an element, Polymer attaches a shadow root f the element and copies the template contents into the shadow tree. -```html - - - +```js +// Import the Polymer library and html helper function +import { PolymerElement, html } from '@polymer/polymer/polymer-element.js'; +// Define the new element as a class +class MyHeader extends PolymerElement { + // Provide a DOM template for the element + static get template () { + // Tag the returned template literal with the html helper function + // to convert it into an instance of HTMLTemplateElement + return html` + + +
+

I'm a header

+ +
+ + `; + } +} +// Tell the browser about the new tag +customElements.define('my-header', MyHeader); ``` - Note that the template includes a ` -

I'm a shadow DOM child element of x-foo.

+

I'm a shadow DOM child element of custom-element.

So am I.

- - ... - + `; +} +... ``` -`index.html` { .caption } +index.html { .caption } + ```html - - - - - -

I have nothing to do with x-foo. Because of encapsulation, x-foo's styles won't leak to me.

+ + + + + + + +

I am outside of custom-element. Because of encapsulation, custom-element's styles won't leak to me.

+ ``` +[See it on Plunker](http://plnkr.co/edit/NKuNTD?p=preview) + For a detailed explanation of shadow DOM as it applies to Polymer, see [Shadow DOM concepts](shadow-dom). For an exploration of the shadow DOM v1 API, see [Shadow DOM v1: Self-Contained Web Components](https://developers.google.com/web/fundamentals/getting-started/primers/shadowdom). @@ -99,47 +95,55 @@ For an exploration of the shadow DOM v1 API, see [Shadow DOM v1: Self-Contained When used in an HTML document, your element will still inherit any styling information that applies to its parent element: -[See it on Plunker](http://plnkr.co/edit/7ugStflqbexg2dNqmtDQ?p=preview) +custom-element.js { .caption} -`x-foo.html` { .caption} -```html - - - + `; +} +... ``` -`index.html` { .caption} -```html - - - +index.html { .caption } - -

I'm sans-serif and blue.

+```html + + + + + + + +

I'm sans-serif and blue.

- -

+ +

+ ``` +[See it on Plunker](http://plnkr.co/edit/jziXon?p=preview) + Styles declared inside shadow DOM will override styles declared outside of it: -[See it on Plunker](http://plnkr.co/edit/0Fid1Gupd0jk9jggAKuv?p=preview) +custom-element.js { .caption} -`x-foo.html` { .caption} -```html - - - + `; +} +... ``` -`index.html` { .caption} +index.html { .caption } + ```html - - - -

I'm blue.

-

+ + + + + + +

I'm blue.

+

+ ``` +[See it on Plunker](http://plnkr.co/edit/XDCXXG?p=preview) + ### Style the host element @@ -172,104 +184,116 @@ The element to which shadow DOM is attached is known as the host. To style the h Inheritable properties of the host element will inherit down the shadow tree, where they apply to the shadow children. -[See it on Plunker](http://plnkr.co/edit/7771DvsQ3iPWnn2gEIf8?p=preview) +custom-element.js { .caption} -`x-foo.html` { .caption} -```html - - - + `; +} +... ``` -`index.html` { .caption} +index.html { .caption } + ```html - - + + + + +

+ ``` -You can also style the host element from outside - for example, using a type selector: - -[See it on Plunker](http://plnkr.co/edit/AHXFX0zeQTbO2rGELTbS?p=preview) - -```css -x-foo { - background-color: blue; -} -``` +[See it on Plunker](http://plnkr.co/edit/BByXie?p=preview) #### Use CSS selectors to style the host element You can use CSS selectors to determine when and how to style the host. In this code sample: -* The selector `:host` matches any `` element -* The selector `:host(.blue)` matches `` elements of class `blue` -* The selector `:host(.red)` matches `` elements of class `red` -* The selector `:host(:hover)` matches `` elements when they are hovered over +* The selector `:host` matches any `` element +* The selector `:host(.blue)` matches `` elements of class `blue` +* The selector `:host(.red)` matches `` elements of class `red` +* The selector `:host(:hover)` matches `` elements when they are hovered over -[See it on Plunker](http://plnkr.co/edit/FsXnCAz65SR6fZ7YKuy6?p=preview) +custom-element.js { .caption} -`x-foo.html` { .caption} -```html - - - +

Hi, from custom-element!

+ `; +} +... ``` -`index.html` { .caption} -```html - +index.html { .caption } - - +```html + + + + + + + ``` +[See it on Plunker](http://plnkr.co/edit/tbPBVG?p=preview) + Descendant selectors after `:host` match elements in the shadow tree. In this example, the CSS selector applies to any `p` element in the shadow tree if the host has class "warning": -[See it on Plunker](http://plnkr.co/edit/MRN9blKg6A3w8G0RkyJD?p=preview) +custom-element.js { .caption} -`x-foo.html` { .caption} -```html - - - + `; +} +... ``` -`index.html` { .caption} -```html - +index.html { .caption } - - +```html + + + + + + + ``` +[See it on Plunker](http://plnkr.co/edit/U7BG6S?p=preview) + Styling with the `:host` selector is one of two instances where rules inside a shadow tree can affect an element outside a shadow tree. The second instance uses the `::slotted()` syntax to apply styling rules to distributed children. See [*Composition and slots* in Eric Bidelman's article on shadow DOM](https://developers.google.com/web/fundamentals/getting-started/primers/shadowdom#composition_slot) for more information. ### Style slotted content (distributed children) @@ -278,110 +302,121 @@ You can create **slots** in an element's template that are populated at runtime. The basic syntax for incorporating slotted content looks like this: -[See it on Plunker](http://plnkr.co/edit/bNvOvQqCEmC4DaoeNtwZ?p=preview) +custom-element.js { .caption} -`x-foo.html` { .caption} -```html - - - ... - +```js +... +static get template() { + return html` +

+ `; +} +... ``` -`index.html` { .caption} -```html - +index.html { .caption } - - I'm a heading! - +```html + + + + + I'm a heading! + ``` +[See it on Plunker](http://plnkr.co/edit/e6m48f?p=preview) + To style slotted content, use the `::slotted()` syntax. **Note:** To work within the Shady CSS scoping shim limitations, and to ensure consistent cross-browser behavior, add a selector to the left of the `::slotted(.classname)` notation (for example, `p ::slotted(.classname)`. `::slotted(*)` selects all slotted content: -[See it on Plunker](http://plnkr.co/edit/pb0D6r15jvvxYVWsZ95U?p=preview) +custom-element.js { .caption} -`x-foo.html` { .caption} -```html - - - ... - +

+

+ `; +} +... ``` -`index.html` { .caption} +index.html { .caption } + ```html - - -
Heading 1. I'm green.
-
Paragraph text. I'm green too.
- + + + + + +
Heading 1. I'm green.
+
Paragraph text. I'm green too.
+ + ``` -[See it on Plunker](http://plnkr.co/edit/Xb4j1r4wEgGuyUM9huFV?p=preview) +[See it on Plunker](http://plnkr.co/edit/jMjMAY?p=preview) You can select by element type: -`x-foo.html` { .caption} -```html - - - ... - + `; +} +... ``` -`index.html` { .caption} -```html - +index.html { .caption } - -

Heading 1. I'm green.

-

Paragraph text. I'm blue.

- +```html + + + + + +

Heading 1. I'm green.

+

Paragraph text. I'm blue.

+ + ``` +[See it on Plunker](http://plnkr.co/edit/rt0jDx?p=preview) + You can select by class: -[See it on Plunker](http://plnkr.co/edit/Ep8AVOHgiwQjtv8x5kwd?p=preview) +custom-element.js { .caption} -`x-foo.html` { .caption} -```html - - - + ``` -When you create the element that will use the styles, include the style module in the opening tag of the style block: +Then style the unresolved element. For example: ```html - - - + ``` -You'll most likely want to package the style module in its own html file. In that case, the element that uses the styles will need to import that file. +Finally, remove the `unresolved` attribute in the element's `ready` callback: -Here's an example: +```js +class MyElement extends PolymerElement(){ + ... + ready(){ + super.ready(); + this.removeAttribute('unresolved'); + ... + } + ... +} +``` -[See it on Plunker](http://plnkr.co/edit/Cd9XdfAF0RNEw5MGOudE?p=preview) +### Style directional text with the :dir() selector -`my-colors.html` { .caption} -```html - - - - +The `:dir()` CSS selector allows for styling text specific to its orientation +(right-to-left or left-to-right). See the [documentation on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir) for more information on the `:dir()` +selector. + +The `DirMixin` provides limited support for the `:dir()` selector. Use of `:dir()` requires the +application to set the `dir` attribute on ``. All elements will use the same direction. + +Individual elements can opt-out of the global direction by setting the `dir` attribute +in HTML or in the `ready` callback, but the text direction of these elements must from then on be handled +manually. + +Setting `dir` on an ancestor (other than `html`) has no effect. + +For elements that extend `PolymerElement`, add `DirMixin` to use +`:dir()` styling. + +Here's an example use of the `:dir()` selector: + +`using-dir-selector.js` { .caption } + +```js +import { PolymerElement, html } from '@polymer/polymer/polymer-element.js'; +import DirMixin from '@polymer/polymer/lib/mixins/dir-mixin.js'; + +class UsingDirSelector extends DirMixin(PolymerElement) { + static get template() { + return html` + + ... + `; + } +} +customElements.define('using-dir-selector', UsingDirSelector); ``` -`x-foo.html` { .caption} +`index.html` { .caption } + ```html - - - - - ... - + + + + + + + + ``` -`index.html` { .caption} -```html - +## Share styles between elements - -``` +### Use style modules {#style-modules} + +The preferred way to share styles is with *style modules*. You can package up styles in a style module, and share them between elements. + +**The following process is a workaround.** While Polymer 3.0 does not use HTMLImports, style modules do. The following process is a workaround for this fact. This process may be updated as required. +{ .alert } + +To create a style module: +1. Use JavaScript to create a `` element: -### Use external stylesheets (deprecated) {#external-stylesheets} + ```js + const styleElement = document.createElement('dom-module'); + ``` -**Deprecated feature.** This experimental feature is now deprecated in favor of -[style modules](#style-modules). It is still supported, but support will -be removed in the future. -{.alert .alert-info} +2. Set the `` element's `innerHTML` property to contain a ``; + ``` -To include a remote stylesheet that applies to your Polymer element's local DOM, -place a special HTML import `` tag with `type="css"` in your -`` that refers to the external stylesheet to load. +3. Register your style module as an element: -For example: + ```js + styleElement.register('style-element'); + ``` -[See it on Plunker](http://plnkr.co/edit/7AvgX9jQApbJoWHbdPkI?p=preview) +You'll most likely want to package the style module in its own JavaScript file. The element that uses the styles will need to import that file. For example: -`style.css` { .caption} -```css -.red { color: red; } -.green { color: green; } -.blue { color: blue; } +```js +import './style-element.js'; ``` -`x-foo.html` { .caption} -```html - - - - - ... - +When you create the element that will use the styles, include the style module in the opening tag of the style block: + +```js + static get template() { + return html` + + + `; + } +} ``` -`index.html` { .caption} -```html - +Here's a complete example: + +index.html { .caption } + +```html + + + + + + +

Style modules

+ +

are useful

+ + +``` + +custom-element.js { .caption } + +```js +import { PolymerElement, html } from '@polymer/polymer/polymer-element.js'; +import './style-element.js'; + +class CustomElement extends PolymerElement { + static get template() { + return html` + + + + +
+

Some styles for custom-element.js are defined in style-element.js, which is a style module.

+

Additional styles are defined in custom-element.js.

+
+ `; + } +} +customElements.define('custom-element', CustomElement); +``` + +style-element.js { .caption } - +```js +const styleElement = document.createElement('dom-module'); +styleElement.innerHTML = + ``; +styleElement.register('style-element'); ``` -## Use `custom-style` in document-level styles {#custom-style} +[See it on Plunker](http://plnkr.co/edit/PNsZA1?p=preview) + +## Use custom-style in document-level styles {#custom-style} Browsers that implement the current Shadow DOM v1 specifications will automatically encapsulate styles, scoping them to the elements in which they were defined. @@ -585,104 +732,114 @@ Some browsers have not implemented the Shadow DOM v1 specifications. To make sur `custom-style` enables a set of polyfills that ensure that styles in your apps and elements behave as you would expect from the Shadow DOM v1 specifications, even in browsers that don't implement these specifications. -To ensure that your styles behave according to the Shadow DOM v1 specifications in all browsers, use `custom-style` when you define *document-level* styles. `custom-style` is not included with `Polymer.Element` and must be imported separately. -`custom-style` is included with the legacy `polymer.html` import. +To ensure that your styles behave according to the Shadow DOM v1 specifications in all browsers, use `custom-style` when you define *document-level* styles: -*Note: You should only use `custom-style` to define styles for the main document. To define styles for an element's local DOM, just use a ` + +``` -In the first code sample, the style for the `p` element “leaks” into Paragraph B in browsers that haven’t implemented the Shadow DOM v1 specs. In the second code sample, the developer has used `custom-style` to wrap the style block, preventing this leak. +`custom-style` is not included in the `@polymer/polymer/polymer-element.js` module. Import `custom-style` from `@polymer/polymer/lib/elements/custom-style.js`: -[See it on Plunker](http://plnkr.co/edit/0o1zuMHgmt4novf2DS8z?p=preview) +index.html { .caption } -`x-foo.html` { .caption} ```html - - - ... - + + - -

Paragraph A: I am in the main DOM. I am red.

- + + +

Paragraph A: I am in the main document. I am red.

+ + ``` -### Syntax and compatibility +[See it on Plunker](http://plnkr.co/edit/FJEC5C?p=preview) -The syntax of `custom-style` has changed. In Polymer 2.x, `` is a wrapper element. You can use a hybrid syntax to ensure compatibility between Polymer 1.x and other versions. +In the following code sample, the developer has used `custom-style` to wrap the document-level style block in index.html, preventing the leak. -Polymer 2.x { .caption} -```html - - - -``` +custom-element.js { .caption} -Hybrid (compatible with 1.x and 2.x) { .caption} -```html - - - +```js +... +static get template() { + return html` +

+ Paragraph B: I am in the shadow DOM of custom-element. Document-level styles in index.html are wrapped in a custom-style block to prevent them from leaking to me. +

+ `; +} +... ``` -Polymer 1.x { .caption} +index.html { .caption} + ```html - + + + + + + + + + +

Paragraph A: I am in the main document. I am red.

+ + ``` + +[See it on Plunker](http://plnkr.co/edit/M6RsuM?p=preview) \ No newline at end of file