0
# Polyfill Support
1

2
Polyfill support for browsers without native web components support, specifically providing ShadyCSS integration for CSS scoping and ShadyDOM patches. This ensures lit-element works correctly in older browsers that don't natively support Shadow DOM or CSS custom properties.
3

4
## Capabilities
5

6
### Polyfill Support Import
7

8
Import and configure polyfill support for browser compatibility.
9

10
```typescript { .api }
11
/**
12
 * Import path for polyfill support module
13
 */
14
import "lit-element/polyfill-support.js";
15
```
16

17
**Usage Examples:**
18

19
```typescript
20
// Import polyfill support before importing lit-element components
21
import "lit-element/polyfill-support.js";
22
import { LitElement, html, css } from "lit-element";
23

24
class PolyfillCompatibleElement extends LitElement {
25
  static styles = css`
26
    :host {
27
      display: block;
28
      background: var(--element-bg, white);
29
      color: var(--element-color, black);
30
    }
31
    
32
    .content {
33
      padding: 16px;
34
      border: 1px solid var(--border-color, #ccc);
35
    }
36
  `;
37

38
  render() {
39
    return html`
40
      <div class="content">
41
        <slot></slot>
42
      </div>
43
    `;
44
  }
45
}
46

47
customElements.define("polyfill-element", PolyfillCompatibleElement);
48
```
49

50
### ShadyCSS Integration
51

52
Automatic integration with ShadyCSS polyfill for CSS custom properties and scoped styles.
53

54
```typescript { .api }
55
/**
56
 * ShadyCSS polyfill integration (automatically configured)
57
 * Provides CSS custom property support and style scoping in polyfilled environments
58
 */
59
```
60

61
**Features:**
62

63
- **CSS Custom Properties**: Enables CSS variables (`var()`) in browsers that don't support them natively
64
- **Style Scoping**: Provides Shadow DOM style encapsulation using class-based scoping
65
- **Adoptable Stylesheets**: Falls back to `<style>` tags when adoptedStyleSheets aren't available
66
- **Runtime Style Updates**: Handles dynamic style changes in polyfilled environments
67

68
**Usage Examples:**
69

70
```typescript
71
import "lit-element/polyfill-support.js";
72
import { LitElement, html, css } from "lit-element";
73

74
class ThemedElement extends LitElement {
75
  static styles = css`
76
    :host {
77
      --primary-color: #007bff;
78
      --secondary-color: #6c757d;
79
      
80
      display: block;
81
      padding: 16px;
82
    }
83

84
    .header {
85
      color: var(--primary-color);
86
      background: var(--header-bg, transparent);
87
      padding: 8px;
88
      border-bottom: 2px solid var(--primary-color);
89
    }
90

91
    .content {
92
      color: var(--text-color, #333);
93
      background: var(--content-bg, white);
94
      padding: 16px;
95
    }
96

97
    .button {
98
      background: var(--primary-color);
99
      color: white;
100
      border: none;
101
      padding: 8px 16px;
102
      border-radius: 4px;
103
      cursor: pointer;
104
    }
105

106
    .button:hover {
107
      background: var(--secondary-color);
108
    }
109
  `;
110

111
  render() {
112
    return html`
113
      <div class="header">
114
        <h2>Themed Component</h2>
115
      </div>
116
      <div class="content">
117
        <p>This component works with CSS custom properties in all browsers.</p>
118
        <button class="button">Styled Button</button>
119
      </div>
120
    `;
121
  }
122
}
123

124
// Set theme variables at document level
125
document.documentElement.style.setProperty('--primary-color', '#28a745');
126
document.documentElement.style.setProperty('--header-bg', '#f8f9fa');
127
```
128

129
### ShadyDOM Integration
130

131
Automatic integration with ShadyDOM polyfill for Shadow DOM functionality.
132

133
```typescript { .api }
134
/**
135
 * ShadyDOM polyfill integration (automatically configured)
136
 * Provides Shadow DOM functionality using light DOM with scoped selectors
137
 */
138
```
139

140
**Features:**
141

142
- **Shadow Root Emulation**: Creates isolated DOM subtrees using class-based scoping
143
- **Slot Distribution**: Implements `<slot>` functionality for content projection
144
- **Event Retargeting**: Ensures events behave as expected in polyfilled Shadow DOM
145
- **CSS Selector Scoping**: Automatically scopes CSS selectors to component boundaries
146

147
**Usage Examples:**
148

149
```typescript
150
import "lit-element/polyfill-support.js";
151
import { LitElement, html, css } from "lit-element";
152

153
class SlottedElement extends LitElement {
154
  static styles = css`
155
    :host {
156
      display: block;
157
      border: 2px solid #ddd;
158
      padding: 16px;
159
    }
160

161
    .header {
162
      font-weight: bold;
163
      margin-bottom: 16px;
164
      padding: 8px;
165
      background: #f0f0f0;
166
    }
167

168
    .content {
169
      padding: 8px;
170
    }
171

172
    ::slotted(h3) {
173
      color: #007bff;
174
      margin: 0 0 8px 0;
175
    }
176

177
    ::slotted(.highlight) {
178
      background: yellow;
179
      padding: 4px;
180
    }
181
  `;
182

183
  render() {
184
    return html`
185
      <div class="header">
186
        <slot name="header">Default Header</slot>
187
      </div>
188
      <div class="content">
189
        <slot></slot>
190
      </div>
191
    `;
192
  }
193
}
194

195
customElements.define("slotted-element", SlottedElement);
196

197
// Usage with content projection:
198
// <slotted-element>
199
//   <h2 slot="header">Custom Header</h2>
200
//   <h3>Main Content Title</h3>
201
//   <p class="highlight">Highlighted paragraph</p>
202
// </slotted-element>
203
```
204

205
### Browser Compatibility
206

207
Information about browser support and compatibility requirements.
208

209
```typescript { .api }
210
/**
211
 * Browser compatibility information
212
 * Polyfill support enables lit-element to work in:
213
 * - Internet Explorer 11
214
 * - Legacy Edge (non-Chromium)
215
 * - Older versions of Chrome, Firefox, and Safari
216
 */
217
```
218

219
**Supported Browsers:**
220

221
- **Internet Explorer 11**: Full support with polyfills
222
- **Legacy Edge**: Complete compatibility 
223
- **Chrome 54+**: Native support (polyfills not needed)
224
- **Firefox 63+**: Native support (polyfills not needed)
225
- **Safari 10.1+**: Partial native support, polyfills improve compatibility
226

227
**Polyfill Requirements:**
228

229
For full compatibility in older browsers, also include:
230

231
```html
232
<!-- Web Components polyfills -->
233
<script src="https://unpkg.com/@webcomponents/webcomponentsjs@^2/webcomponents-bundle.js"></script>
234

235
<!-- CSS Custom Properties polyfill (IE11) -->
236
<script src="https://unpkg.com/css-vars-ponyfill@^2"></script>
237
```
238

239
**Usage Examples:**
240

241
```html
242
<!DOCTYPE html>
243
<html>
244
<head>
245
  <meta charset="utf-8">
246
  <title>Polyfill Compatible App</title>
247
  
248
  <!-- Load polyfills first -->
249
  <script src="https://unpkg.com/@webcomponents/webcomponentsjs@^2/webcomponents-bundle.js"></script>
250
  
251
  <!-- Load lit-element polyfill support -->
252
  <script type="module">
253
    import 'lit-element/polyfill-support.js';
254
    import './my-components.js';
255
  </script>
256
</head>
257
<body>
258
  <my-app></my-app>
259
</body>
260
</html>
261
```
262

263
### Performance Considerations
264

265
Tips for optimal performance when using polyfills.
266

267
```typescript { .api }
268
/**
269
 * Performance considerations for polyfilled environments
270
 * - Minimize dynamic style changes
271
 * - Use static styles where possible
272
 * - Avoid deep CSS selector nesting
273
 * - Cache DOM queries
274
 */
275
```
276

277
**Best Practices:**
278

279
- **Static Styles**: Define styles in `static styles` property rather than dynamically
280
- **Minimal DOM Manipulation**: Reduce direct DOM queries and modifications
281
- **CSS Optimization**: Use simple selectors and avoid complex CSS that's expensive to polyfill
282
- **Bundle Splitting**: Load polyfills conditionally based on browser support
283

284
**Usage Examples:**
285

286
```typescript
287
import "lit-element/polyfill-support.js";
288
import { LitElement, html, css } from "lit-element";
289

290
class OptimizedElement extends LitElement {
291
  // Use static styles for better polyfill performance
292
  static styles = css`
293
    :host {
294
      display: block;
295
    }
296
    
297
    /* Simple selectors work better with polyfills */
298
    .item {
299
      padding: 8px;
300
      margin: 4px 0;
301
    }
302
    
303
    .item-active {
304
      background: #e3f2fd;
305
    }
306
  `;
307

308
  items = ['Item 1', 'Item 2', 'Item 3'];
309
  activeIndex = 0;
310

311
  render() {
312
    return html`
313
      <div>
314
        ${this.items.map((item, index) => html`
315
          <div 
316
            class="item ${index === this.activeIndex ? 'item-active' : ''}"
317
            @click=${() => this.activeIndex = index}
318
          >
319
            ${item}
320
          </div>
321
        `)}
322
      </div>
323
    `;
324
  }
325
}
326
```