0
# LitElement
1

2
LitElement is a simple base class for creating fast, lightweight web components. It extends the Lit project's ReactiveElement with lit-html templating capabilities, providing reactive properties, lifecycle callbacks, scoped CSS styling, and declarative HTML templating for building efficient custom elements.
3

4
## Package Information
5

6
- **Package Name**: lit-element
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install lit-element`
10

11
## Core Imports
12

13
```typescript
14
import { LitElement, html, css } from "lit-element";
15
```
16

17
CommonJS:
18

19
```javascript
20
const { LitElement, html, css } = require("lit-element");
21
```
22

23
Decorators (for TypeScript):
24

25
```typescript
26
import { customElement, property, state, query } from "lit-element/decorators.js";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { LitElement, html, css } from "lit-element";
33
import { customElement, property } from "lit-element/decorators.js";
34

35
@customElement("my-element")
36
class MyElement extends LitElement {
37
  static styles = css`
38
    :host {
39
      display: block;
40
      padding: 16px;
41
    }
42
    .highlight {
43
      color: blue;
44
    }
45
  `;
46

47
  @property({ type: String })
48
  name = "World";
49

50
  @property({ type: Number })
51
  count = 0;
52

53
  render() {
54
    return html`
55
      <div class="highlight">
56
        <h1>Hello, ${this.name}!</h1>
57
        <p>Count: ${this.count}</p>
58
        <button @click=${this._increment}>Increment</button>
59
      </div>
60
    `;
61
  }
62

63
  private _increment() {
64
    this.count++;
65
  }
66
}
67
```
68

69
## Architecture
70

71
LitElement is built on several key architectural components:
72

73
- **ReactiveElement Base**: Provides reactive property system, lifecycle callbacks, and basic custom element functionality
74
- **lit-html Integration**: Efficient HTML templating with declarative syntax and optimal re-rendering
75
- **CSS Scoping**: Shadow DOM-based styling with scoped CSS and adoptedStyleSheets support
76
- **Decorator System**: TypeScript decorators for enhanced developer experience
77
- **Property System**: Reactive property management with attribute reflection and type conversion
78
- **Lifecycle Management**: Standard custom element lifecycle with additional update phases
79

80
## Capabilities
81

82
### Core Element Class
83

84
The main LitElement class that extends ReactiveElement with lit-html templating functionality.
85

86
```typescript { .api }
87
class LitElement extends ReactiveElement {
88
  readonly renderOptions: RenderOptions;
89
  
90
  protected createRenderRoot(): Element | ShadowRoot;
91
  protected update(changedProperties: PropertyValues): void;
92
  protected render(): unknown;
93
  connectedCallback(): void;
94
  disconnectedCallback(): void;
95
}
96
```
97

98
[Core Element](./core-element.md)
99

100
### Property System
101

102
Reactive property management with decorators, type conversion, and change detection for building reactive custom elements.
103

104
```typescript { .api }
105
function property(options?: PropertyDeclaration): PropertyDecorator;
106
function state(options?: StateDeclaration): PropertyDecorator;
107

108
interface PropertyDeclaration {
109
  type?: TypeHint;
110
  attribute?: boolean | string;
111
  reflect?: boolean;
112
  converter?: AttributeConverter;
113
  noAccessor?: boolean;
114
  hasChanged?: HasChanged;
115
}
116
```
117

118
[Property System](./property-system.md)
119

120
### Template System
121

122
HTML templating with lit-html providing efficient rendering, event binding, and directive support.
123

124
```typescript { .api }
125
function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
126
function svg(strings: TemplateStringsArray, ...values: unknown[]): SVGTemplateResult;
127
function render(value: unknown, container: Element | DocumentFragment, options?: RenderOptions): RootPart;
128

129
const nothing: symbol;
130
const noChange: symbol;
131
```
132

133
[Template System](./template-system.md)
134

135
### CSS Styling
136

137
Scoped CSS system with shadow DOM support, providing isolated styling and efficient style application.
138

139
```typescript { .api }
140
function css(strings: TemplateStringsArray, ...values: (CSSResult | number)[]): CSSResult;
141
function unsafeCSS(value: string): CSSResult;
142

143
class CSSResult {
144
  readonly cssText: string;
145
  readonly strings?: TemplateStringsArray;
146
  readonly values?: readonly CSSResult[];
147
}
148

149
type CSSResultGroup = CSSResult | CSSResultArray;
150
interface CSSResultArray extends Array<CSSResultGroup> {}
151
```
152

153
[CSS Styling](./css-styling.md)
154

155
### Decorators
156

157
TypeScript decorators for enhanced development experience with declarative property and element configuration.
158

159
```typescript { .api }
160
function customElement(tagName: string): ClassDecorator;
161
function property(options?: PropertyDeclaration): PropertyDecorator;
162
function state(options?: StateDeclaration): PropertyDecorator;
163
function query(selector: string, cache?: boolean): PropertyDecorator;
164
function queryAll(selector: string): PropertyDecorator;
165
```
166

167
[Decorators](./decorators.md)
168

169
### Directives
170

171
Built-in directives for advanced templating patterns, conditional rendering, and performance optimization.
172

173
```typescript { .api }
174
function repeat<T>(
175
  items: Iterable<T>,
176
  keyFn: KeyFn<T>,
177
  template: ItemTemplate<T>
178
): DirectiveResult<typeof RepeatDirective>;
179

180
function classMap(classInfo: ClassInfo): DirectiveResult<typeof ClassMapDirective>;
181
function styleMap(styleInfo: StyleInfo): DirectiveResult<typeof StyleMapDirective>;
182
function when<T, F>(
183
  condition: boolean,
184
  trueCase: () => T,
185
  falseCase?: () => F
186
): T | F | typeof nothing;
187

188
function map<T>(items: Iterable<T>, template: (item: T, index: number) => unknown): DirectiveResult<typeof MapDirective>;
189
function join<T>(items: Iterable<T>, joiner: unknown): DirectiveResult<typeof JoinDirective>;
190
function until(promise: Promise<unknown>, ...defaultContent: unknown[]): DirectiveResult<typeof UntilDirective>;
191
function asyncAppend(asyncIterable: AsyncIterable<unknown>): DirectiveResult<typeof AsyncAppendDirective>;
192
function asyncReplace(asyncIterable: AsyncIterable<unknown>): DirectiveResult<typeof AsyncReplaceDirective>;
193
```
194

195
[Directives](./directives.md)
196

197
### Polyfill Support
198

199
Browser compatibility support for older browsers without native web components support, including ShadyCSS and ShadyDOM integration.
200

201
```typescript { .api }
202
import "lit-element/polyfill-support.js";
203
```
204

205
[Polyfill Support](./polyfill-support.md)
206

207
## Types
208

209
### Core Types
210

211
```typescript { .api }
212
interface PropertyValues extends Map<PropertyKey, unknown> {}
213

214
interface RenderOptions {
215
  host?: object;
216
  renderBefore?: ChildNode | null;
217
  isConnected?: boolean;
218
}
219

220
type TypeHint = 
221
  | typeof String 
222
  | typeof Number 
223
  | typeof Boolean 
224
  | typeof Array 
225
  | typeof Object;
226

227
interface HasChanged {
228
  (value: unknown, oldValue: unknown): boolean;
229
}
230

231
interface AttributeConverter<Type = unknown, TypeHint = unknown> {
232
  fromAttribute?(value: string | null, type?: TypeHint): Type;
233
  toAttribute?(value: Type, type?: TypeHint): unknown;
234
}
235

236
interface ReactiveController {
237
  hostConnected?(): void;
238
  hostDisconnected?(): void;
239
  hostUpdate?(): void;
240
  hostUpdated?(): void;
241
}
242

243
interface ReactiveControllerHost {
244
  addController(controller: ReactiveController): void;
245
  removeController(controller: ReactiveController): void;
246
  requestUpdate(name?: PropertyKey, oldValue?: unknown, options?: object): void;
247
  readonly updateComplete: Promise<boolean>;
248
}
249
```