0
# lit-html
1

2
lit-html is an efficient, expressive, and extensible HTML templating library for JavaScript that enables developers to write HTML templates using template literals with embedded JavaScript expressions. It provides a powerful template tag `html` for creating templates and a `render` function for efficiently rendering these templates to the DOM with automatic updates when values change.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { html, render } from 'lit-html';
15
```
16

17
For specific features:
18

19
```typescript
20
import { html, render, svg, mathml, nothing, noChange } from 'lit-html';
21
import { directive, Directive } from 'lit-html/directive.js';
22
import { AsyncDirective } from 'lit-html/async-directive.js';
23
import { repeat } from 'lit-html/directives/repeat.js';
24
import { classMap } from 'lit-html/directives/class-map.js';
25
import { isServer } from 'lit-html/is-server.js';
26
```
27

28
## Basic Usage
29

30
```typescript
31
import { html, render } from 'lit-html';
32

33
// Create a template
34
const myTemplate = (name: string) => html`<h1>Hello, ${name}!</h1>`;
35

36
// Render to the DOM
37
render(myTemplate('World'), document.body);
38

39
// Dynamic updates - only changed parts re-render
40
render(myTemplate('Universe'), document.body);
41
```
42

43
## Architecture
44

45
lit-html is built around several key concepts:
46

47
- **Template Literals**: JavaScript template literals with embedded expressions
48
- **Incremental DOM**: Efficient updates by patching only changed parts
49
- **Template Results**: Lazy evaluation - templates describe DOM structure without creating it
50
- **Parts System**: Internal representation of dynamic portions of templates
51
- **Directive System**: Extensible system for custom template behaviors
52
- **Static Templates**: Optimization for templates with static parts
53
- **Server-Side Rendering**: Support for rendering templates on the server
54

55
## Capabilities
56

57
### Core Template System
58

59
Essential template creation and rendering functionality for building dynamic HTML interfaces.
60

61
```typescript { .api }
62
function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
63
function svg(strings: TemplateStringsArray, ...values: unknown[]): SVGTemplateResult;
64
function mathml(strings: TemplateStringsArray, ...values: unknown[]): MathMLTemplateResult;
65
function render(
66
  value: unknown,
67
  container: HTMLElement | DocumentFragment,
68
  options?: RenderOptions
69
): RootPart;
70
```
71

72
[Core Templates](./core-templates.md)
73

74
### Built-in Directives
75

76
Comprehensive collection of directives for common templating patterns including conditional rendering, lists, styling, and performance optimization.
77

78
```typescript { .api }
79
// Conditional rendering
80
function when<C, T, F = undefined>(
81
  condition: C,
82
  trueCase: (c: Exclude<C, Falsy>) => T,
83
  falseCase?: (c: Extract<C, Falsy>) => F
84
): C extends Falsy ? F : T;
85

86
// List rendering with efficient updates
87
function repeat<T>(
88
  items: Iterable<T>,
89
  keyFnOrTemplate: KeyFn<T> | ItemTemplate<T>,
90
  template?: ItemTemplate<T>
91
): DirectiveResult;
92

93
// Dynamic CSS classes
94
function classMap(classInfo: ClassInfo): DirectiveResult;
95

96
// Dynamic inline styles
97
function styleMap(styleInfo: StyleInfo): DirectiveResult;
98
```
99

100
[Built-in Directives](./built-in-directives.md)
101

102
### Custom Directive System
103

104
Framework for creating custom directives to extend template functionality with lifecycle management and state.
105

106
```typescript { .api }
107
function directive<C extends DirectiveClass>(c: C): (...values: DirectiveParameters<InstanceType<C>>) => DirectiveResult<C>;
108

109
abstract class Directive {
110
  abstract render(...props: Array<unknown>): unknown;
111
  update(part: Part, props: Array<unknown>): unknown;
112
}
113

114
abstract class AsyncDirective extends Directive {
115
  isConnected: boolean;
116
  setValue(value: unknown): void;
117
  protected disconnected(): void;
118
  protected reconnected(): void;
119
}
120
```
121

122
[Custom Directives](./custom-directives.md)
123

124
### Static Templates
125

126
Optimization system for templates with static parts that don't change, enabling better performance and smaller bundle sizes.
127

128
```typescript { .api }
129
function literal(strings: TemplateStringsArray, ...values: unknown[]): StaticValue;
130
function unsafeStatic(value: string): StaticValue;
131

132
// Enhanced template functions with static support
133
function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
134
function svg(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
135
function mathml(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
136
```
137

138
[Static Templates](./static-templates.md)
139

140
### Polyfill Support
141

142
Platform support utilities for environments that need polyfills for web components functionality.
143

144
```typescript { .api }
145
/**
146
 * Installs platform polyfills to support lit-html in older browsers.
147
 * Call this once before using lit-html in environments that need polyfills.
148
 */
149
function installPolyfills(): void;
150

151
/**
152
 * Polyfill support interface for customizing template creation.
153
 */
154
interface PolyfillSupport {
155
  (template: typeof Template, childPart: typeof ChildPart): void;
156
}
157
```
158

159
### Debug and Development APIs
160

161
Development and debugging utilities available in dev mode builds. These APIs are not available in production builds.
162

163
```typescript { .api }
164
/**
165
 * Unstable debug APIs for development tooling and visualization.
166
 * Only available when DEV_MODE is true and window.emitLitDebugLogEvents is set.
167
 */
168
namespace LitUnstable {
169
  namespace DebugLog {
170
    interface Entry {
171
      kind: 'template prep' | 'begin render' | 'end render' | 'template instantiated' 
172
           | 'template updating' | 'commit text' | 'commit node' | 'commit attribute'
173
           | 'commit property' | 'commit boolean attribute' | 'commit event listener';
174
      // Additional properties vary by entry type
175
    }
176
  }
177
}
178

179
/**
180
 * Global flag to enable debug event emission in development mode.
181
 * Set this before using lit-html to receive 'lit-debug' events on window.
182
 */
183
declare global {
184
  interface Window {
185
    emitLitDebugLogEvents?: boolean;
186
  }
187
}
188
```
189

190
**Usage Examples:**
191

192
```typescript
193
// Enable debug logging (development only)
194
if (process.env.NODE_ENV === 'development') {
195
  window.emitLitDebugLogEvents = true;
196
  
197
  // Listen for debug events
198
  window.addEventListener('lit-debug', (event) => {
199
    console.log('Lit debug event:', event.detail);
200
    
201
    switch (event.detail.kind) {
202
      case 'begin render':
203
        console.log('Starting render with value:', event.detail.value);
204
        break;
205
      case 'template prep':
206
        console.log('Template prepared:', event.detail.template);
207
        break;
208
      case 'commit text':
209
        console.log('Text committed:', event.detail.value);
210
        break;
211
    }
212
  });
213
}
214
```
215

216
## Core Types
217

218
```typescript { .api }
219
interface TemplateResult<T extends ResultType = ResultType> {
220
  readonly strings: TemplateStringsArray;
221
  readonly values: unknown[];
222
}
223

224
type HTMLTemplateResult = TemplateResult<typeof HTML_RESULT>;
225
type SVGTemplateResult = TemplateResult<typeof SVG_RESULT>;
226
type MathMLTemplateResult = TemplateResult<typeof MATHML_RESULT>;
227

228
interface RenderOptions {
229
  host?: object;
230
  renderBefore?: ChildNode | null;
231
  creationScope?: { importNode(node: Node, deep?: boolean): Node };
232
  isConnected?: boolean;
233
}
234

235
interface RootPart extends ChildPart {
236
  setConnected(isConnected: boolean): void;
237
}
238

239
// Sentinel values
240
const nothing: unique symbol;
241
const noChange: unique symbol;
242
```