0
# Core Element
1

2
The LitElement class is the main base class that extends ReactiveElement with lit-html templating functionality. It provides the foundation for creating reactive web components with efficient rendering and property management.
3

4
## Capabilities
5

6
### LitElement Class
7

8
Main base class that manages element properties and attributes, and renders a lit-html template.
9

10
```typescript { .api }
11
/**
12
 * Base element class that manages element properties and attributes, and
13
 * renders a lit-html template.
14
 */
15
class LitElement extends ReactiveElement {
16
  /**
17
   * Readonly render options for configuring lit-html rendering
18
   */
19
  readonly renderOptions: RenderOptions;
20

21
  /**
22
   * Creates the render root for the element (typically shadow root)
23
   * @returns Element or ShadowRoot where content will be rendered
24
   */
25
  protected createRenderRoot(): Element | ShadowRoot;
26

27
  /**
28
   * Updates the element. This method reflects property values to attributes
29
   * and calls render to render DOM via lit-html
30
   * @param changedProperties Map of changed properties with old values
31
   */
32
  protected update(changedProperties: PropertyValues): void;
33

34
  /**
35
   * Invoked on each update to perform rendering tasks. Should return
36
   * any value renderable by lit-html's ChildPart
37
   * @returns Template result, string, number, or other renderable value
38
   */
39
  protected render(): unknown;
40

41
  /**
42
   * Invoked when the component is added to the document's DOM
43
   */
44
  connectedCallback(): void;
45

46
  /**
47
   * Invoked when the component is removed from the document's DOM
48
   */
49
  disconnectedCallback(): void;
50
}
51
```
52

53
**Usage Examples:**
54

55
```typescript
56
import { LitElement, html, css } from "lit-element";
57

58
class MyElement extends LitElement {
59
  static styles = css`
60
    :host {
61
      display: block;
62
      padding: 16px;
63
    }
64
  `;
65

66
  render() {
67
    return html`<p>Hello from LitElement!</p>`;
68
  }
69
}
70

71
customElements.define("my-element", MyElement);
72
```
73

74
### ReactiveElement Base Class
75

76
Base class providing reactive properties and lifecycle management (re-exported from @lit/reactive-element).
77

78
```typescript { .api }
79
/**
80
 * Base class for creating reactive custom elements
81
 */
82
class ReactiveElement extends HTMLElement {
83
  /**
84
   * Static property declarations for reactive properties
85
   */
86
  static properties: PropertyDeclarations;
87

88
  /**
89
   * Static styles applied to the element's shadow root
90
   */
91
  static styles?: CSSResultGroup;
92

93
  /**
94
   * Element lifecycle callback for when element is connected to DOM
95
   */
96
  connectedCallback(): void;
97

98
  /**
99
   * Element lifecycle callback for when element is disconnected from DOM
100
   */
101
  disconnectedCallback(): void;
102

103
  /**
104
   * Element lifecycle callback for when element is moved to new document
105
   */
106
  adoptedCallback(): void;
107

108
  /**
109
   * Element lifecycle callback for when attributes change
110
   */
111
  attributeChangedCallback(name: string, oldValue: string | null, value: string | null): void;
112

113
  /**
114
   * Requests an update which will trigger the update lifecycle
115
   */
116
  requestUpdate(name?: PropertyKey, oldValue?: unknown, options?: RequestUpdateOptions): void;
117

118
  /**
119
   * Performs the update, calling lifecycle methods and rendering
120
   */
121
  protected performUpdate(): void | Promise<unknown>;
122

123
  /**
124
   * Override point for modification before property values are used in update
125
   */
126
  protected willUpdate(changedProperties: PropertyValues): void;
127

128
  /**
129
   * Override point for modification after update has completed
130
   */
131
  protected updated(changedProperties: PropertyValues): void;
132

133
  /**
134
   * Override point for determining if update should proceed
135
   */
136
  protected shouldUpdate(changedProperties: PropertyValues): boolean;
137

138
  /**
139
   * Creates render root (shadow root by default)
140
   */
141
  protected createRenderRoot(): Element | ShadowRoot;
142

143
  /**
144
   * Returns array of styles to apply to render root
145
   */
146
  protected getStyles(): CSSResultGroup | undefined;
147
}
148
```
149

150
### Render Options
151

152
Configuration options for lit-html rendering.
153

154
```typescript { .api }
155
interface RenderOptions {
156
  /**
157
   * Host object for event listeners and other contextual data
158
   */
159
  host?: object;
160

161
  /**
162
   * Node before which to render content
163
   */
164
  renderBefore?: ChildNode | null;
165

166
  /**
167
   * Whether the template is connected to the live DOM
168
   */
169
  isConnected?: boolean;
170

171
  /**
172
   * Scope name for ShadyCSS compatibility
173
   */
174
  scope?: string;
175
}
176
```
177

178
### Property Values
179

180
Map of changed properties passed to lifecycle methods.
181

182
```typescript { .api }
183
/**
184
 * Map of property changes with property names as keys and old values as values
185
 */
186
interface PropertyValues extends Map<PropertyKey, unknown> {
187
  /**
188
   * Get the old value for a property
189
   */
190
  get(key: PropertyKey): unknown;
191

192
  /**
193
   * Check if a property has changed
194
   */
195
  has(key: PropertyKey): boolean;
196

197
  /**
198
   * Iterate over changed properties
199
   */
200
  [Symbol.iterator](): IterableIterator<[PropertyKey, unknown]>;
201
}
202
```
203

204
### Lifecycle Methods
205

206
Standard custom element and reactive element lifecycle methods.
207

208
```typescript { .api }
209
/**
210
 * Called when element is connected to DOM
211
 */
212
connectedCallback(): void;
213

214
/**
215
 * Called when element is disconnected from DOM
216
 */
217
disconnectedCallback(): void;
218

219
/**
220
 * Called when element is moved to new document
221
 */
222
adoptedCallback(): void;
223

224
/**
225
 * Called when observed attributes change
226
 */
227
attributeChangedCallback(name: string, oldValue: string | null, value: string | null): void;
228

229
/**
230
 * Called before update to allow property modification
231
 */
232
protected willUpdate(changedProperties: PropertyValues): void;
233

234
/**
235
 * Called after update has completed
236
 */
237
protected updated(changedProperties: PropertyValues): void;
238

239
/**
240
 * Called to determine if update should proceed
241
 */
242
protected shouldUpdate(changedProperties: PropertyValues): boolean;
243
```
244

245
**Usage Examples:**
246

247
```typescript
248
import { LitElement, html, PropertyValues } from "lit-element";
249

250
class MyElement extends LitElement {
251
  connectedCallback() {
252
    super.connectedCallback();
253
    console.log("Element connected to DOM");
254
    this.addEventListener("click", this._handleClick);
255
  }
256

257
  disconnectedCallback() {
258
    super.disconnectedCallback();
259
    console.log("Element disconnected from DOM");
260
    this.removeEventListener("click", this._handleClick);
261
  }
262

263
  protected willUpdate(changedProperties: PropertyValues) {
264
    console.log("About to update:", Array.from(changedProperties.keys()));
265
  }
266

267
  protected updated(changedProperties: PropertyValues) {
268
    console.log("Updated:", Array.from(changedProperties.keys()));
269
  }
270

271
  protected shouldUpdate(changedProperties: PropertyValues): boolean {
272
    // Only update if specific properties changed
273
    return changedProperties.has("importantProperty");
274
  }
275

276
  private _handleClick(e: Event) {
277
    console.log("Element clicked");
278
  }
279

280
  render() {
281
    return html`<p>Lifecycle example</p>`;
282
  }
283
}
284
```
285

286
### Reactive Controller System
287

288
System for creating reusable behaviors that can be shared across elements.
289

290
```typescript { .api }
291
/**
292
 * Interface for objects that can host Reactive Controllers
293
 */
294
interface ReactiveControllerHost {
295
  /**
296
   * Registers a controller to participate in the element's lifecycle
297
   */
298
  addController(controller: ReactiveController): void;
299

300
  /**
301
   * Removes a controller from the host
302
   */
303
  removeController(controller: ReactiveController): void;
304

305
  /**
306
   * Requests an update of the host element
307
   */
308
  requestUpdate(name?: PropertyKey, oldValue?: unknown, options?: object): void;
309

310
  /**
311
   * Promise that resolves when the host has completed updating
312
   */
313
  readonly updateComplete: Promise<boolean>;
314
}
315

316
/**
317
 * Interface for objects that participate in the lifecycle of a ReactiveElement
318
 */
319
interface ReactiveController {
320
  /**
321
   * Called when the host is connected to the DOM
322
   */
323
  hostConnected?(): void;
324

325
  /**
326
   * Called when the host is disconnected from the DOM
327
   */
328
  hostDisconnected?(): void;
329

330
  /**
331
   * Called during the host's update, before the host's own update
332
   */
333
  hostUpdate?(): void;
334

335
  /**
336
   * Called after the host has updated
337
   */
338
  hostUpdated?(): void;
339
}
340
```
341

342
**Usage Examples:**
343

344
```typescript
345
import { LitElement, html, ReactiveController, ReactiveControllerHost } from "lit-element";
346

347
class TimerController implements ReactiveController {
348
  private host: ReactiveControllerHost;
349
  private intervalId?: number;
350
  
351
  value = 0;
352

353
  constructor(host: ReactiveControllerHost, private interval = 1000) {
354
    this.host = host;
355
    host.addController(this);
356
  }
357

358
  hostConnected() {
359
    this.intervalId = window.setInterval(() => {
360
      this.value++;
361
      this.host.requestUpdate();
362
    }, this.interval);
363
  }
364

365
  hostDisconnected() {
366
    if (this.intervalId) {
367
      clearInterval(this.intervalId);
368
      this.intervalId = undefined;
369
    }
370
  }
371
}
372

373
class MyElement extends LitElement {
374
  private timer = new TimerController(this);
375

376
  render() {
377
    return html`<p>Timer: ${this.timer.value}</p>`;
378
  }
379
}
380
```