0
# Static Templates
1

2
Optimization system for templates with static parts that don't change, enabling better performance and smaller bundle sizes through compile-time optimizations.
3

4
## Capabilities
5

6
### Static Value Creation
7

8
#### literal Function
9

10
Creates static values from template literals for compile-time optimization.
11

12
```typescript { .api }
13
/**
14
 * Tags a string literal so that it behaves like part of the static template
15
 * strings instead of a dynamic value. Static values can be changed, but they
16
 * will cause a complete re-render since they effectively create a new template.
17
 * @param strings - Template strings array
18
 * @param values - Static values (must be other literal results or unsafeStatic values)
19
 * @returns StaticValue for use in static templates
20
 */
21
function literal(
22
  strings: TemplateStringsArray,
23
  ...values: unknown[]
24
): StaticValue;
25
```
26

27
**Usage Examples:**
28

29
```typescript
30
import { html, literal } from 'lit-html/static.js';
31

32
// Static tag names
33
const tagName = literal`div`;
34
const template = html`<${tagName}>Content</${tagName}>`;
35

36
// Static attribute names
37
const attrName = literal`data-id`;
38
const withStaticAttr = html`<span ${attrName}="123">Text</span>`;
39

40
// Combining static values
41
const className = literal`my-class`;
42
const id = literal`my-id`;
43
const combined = html`<div class="${className}" id="${id}">Content</div>`;
44
```
45

46
#### unsafeStatic Function
47

48
Creates static values from raw strings for advanced use cases requiring dynamic static content.
49

50
```typescript { .api }
51
/**
52
 * Wraps a string so that it behaves like part of the static template
53
 * strings instead of a dynamic value. Note that this function is unsafe
54
 * to use on untrusted content, as it will be directly parsed into HTML.
55
 * @param value - String to treat as static (must be trusted)
56
 * @returns StaticValue for use in static templates
57
 */
58
function unsafeStatic(value: string): StaticValue;
59
```
60

61
**Usage Examples:**
62

63
```typescript
64
import { html, unsafeStatic } from 'lit-html/static.js';
65

66
// Dynamic static tag names (use with caution)
67
const createElementTemplate = (tagName: string) => {
68
  const tag = unsafeStatic(tagName);
69
  return html`<${tag}>Dynamic element</${tag}>`;
70
};
71

72
// Static attribute names from configuration
73
const createTemplate = (config: { idAttr: string }) => {
74
  const idAttr = unsafeStatic(config.idAttr);
75
  return html`<div ${idAttr}="value">Content</div>`;
76
};
77
```
78

79
### Enhanced Template Functions
80

81
Template functions with static value support for optimized rendering.
82

83
#### Static HTML Template Function
84

85
Enhanced HTML template function that supports static values for optimization.
86

87
```typescript { .api }
88
/**
89
 * Interprets a template literal as an HTML template that can efficiently
90
 * render to and update a container. Includes static value support.
91
 * @param strings - Template strings array
92
 * @param values - Template expression values (may include StaticValues)
93
 * @returns TemplateResult for rendering
94
 */
95
function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
96
```
97

98
**Usage Examples:**
99

100
```typescript
101
import { html, literal } from 'lit-html/static.js';
102

103
// Static element structure
104
const elementType = literal`article`;
105
const template = html`
106
  <${elementType} class="post">
107
    <h1>Title</h1>
108
    <p>Content goes here</p>
109
  </${elementType}>
110
`;
111

112
// Static attributes with dynamic values
113
const dataAttr = literal`data-post-id`;
114
const postTemplate = (id: number) => html`
115
  <article ${dataAttr}="${id}">
116
    <h1>Post ${id}</h1>
117
  </article>
118
`;
119
```
120

121
#### Static SVG Template Function
122

123
Enhanced SVG template function that supports static values for optimized vector graphics.
124

125
```typescript { .api }
126
/**
127
 * Interprets a template literal as an SVG template that can efficiently
128
 * render to and update a container. Includes static value support.
129
 * @param strings - Template strings array
130
 * @param values - Template expression values (may include StaticValues)
131
 * @returns TemplateResult for rendering
132
 */
133
function svg(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
134
```
135

136
**Usage Examples:**
137

138
```typescript
139
import { html, svg, literal } from 'lit-html/static.js';
140

141
// Static SVG elements
142
const shapeType = literal`circle`;
143
const iconTemplate = (size: number) => html`
144
  <svg viewBox="0 0 100 100" width="${size}" height="${size}">
145
    ${svg`<${shapeType} cx="50" cy="50" r="40" fill="currentColor" />`}
146
  </svg>
147
`;
148
```
149

150
#### Static MathML Template Function
151

152
Enhanced MathML template function that supports static values for optimized mathematical notation.
153

154
```typescript { .api }
155
/**
156
 * Interprets a template literal as MathML fragment that can efficiently
157
 * render to and update a container. Includes static value support.
158
 * @param strings - Template strings array
159
 * @param values - Template expression values (may include StaticValues)
160
 * @returns TemplateResult for rendering
161
 */
162
function mathml(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
163
```
164

165
### Static Template Wrapper
166

167
#### withStatic Function
168

169
Wraps any template tag function to add static value support.
170

171
```typescript { .api }
172
/**
173
 * Wraps a lit-html template tag (html, svg, or mathml) to add static value support.
174
 * @param coreTag - The core template tag function to enhance
175
 * @returns Enhanced template tag function with static support
176
 */
177
function withStatic(
178
  coreTag: typeof coreHtml | typeof coreSvg | typeof coreMathml
179
): (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult;
180
```
181

182
**Usage Examples:**
183

184
```typescript
185
import { html as coreHtml } from 'lit-html';
186
import { withStatic, literal } from 'lit-html/static.js';
187

188
// Create custom static-enabled template function
189
const customHtml = withStatic(coreHtml);
190

191
const tagName = literal`section`;
192
const template = customHtml`<${tagName}>Content</${tagName}>`;
193
```
194

195
## Advanced Static Template Patterns
196

197
### Component Templates with Static Structure
198

199
```typescript
200
import { html, literal } from 'lit-html/static.js';
201

202
class MyComponent {
203
  static tagName = literal`my-component`;
204
  
205
  render(content: string) {
206
    const tag = MyComponent.tagName;
207
    return html`
208
      <${tag} class="component">
209
        <div class="content">${content}</div>
210
      </${tag}>
211
    `;
212
  }
213
}
214
```
215

216
### Configuration-Driven Static Templates
217

218
```typescript
219
import { html, unsafeStatic } from 'lit-html/static.js';
220

221
interface TemplateConfig {
222
  containerTag: string;
223
  titleTag: string;
224
  contentClass: string;
225
}
226

227
const createTemplate = (config: TemplateConfig) => {
228
  const container = unsafeStatic(config.containerTag);
229
  const title = unsafeStatic(config.titleTag);
230
  const contentClass = unsafeStatic(config.contentClass);
231
  
232
  return (titleText: string, content: string) => html`
233
    <${container}>
234
      <${title}>${titleText}</${title}>
235
      <div class="${contentClass}">${content}</div>
236
    </${container}>
237
  `;
238
};
239

240
// Usage
241
const articleTemplate = createTemplate({
242
  containerTag: 'article',
243
  titleTag: 'h1', 
244
  contentClass: 'article-content'
245
});
246
```
247

248
### Static Attribute Names
249

250
```typescript
251
import { html, literal } from 'lit-html/static.js';
252

253
// Define static attribute names for reuse
254
const dataIdAttr = literal`data-id`;
255
const ariaLabelAttr = literal`aria-label`;
256

257
const accessibleButton = (id: string, label: string, text: string) => html`
258
  <button ${dataIdAttr}="${id}" ${ariaLabelAttr}="${label}">
259
    ${text}
260
  </button>
261
`;
262
```
263

264
### Performance Considerations
265

266
Static templates provide performance benefits by:
267

268
1. **Reduced Template Creation**: Static parts are processed at compile time
269
2. **Smaller Runtime Size**: Less dynamic template processing code
270
3. **Better Caching**: Static templates can be more efficiently cached
271
4. **Compile-time Optimization**: Tools can optimize static template structures
272

273
```typescript
274
import { html, literal } from 'lit-html/static.js';
275

276
// This template structure is optimized at compile time
277
const optimizedTemplate = (data: any[]) => {
278
  const tableTag = literal`table`;
279
  const rowTag = literal`tr`;
280
  const cellTag = literal`td`;
281
  
282
  return html`
283
    <${tableTag} class="data-table">
284
      ${data.map(item => html`
285
        <${rowTag}>
286
          <${cellTag}>${item.name}</${cellTag}>
287
          <${cellTag}>${item.value}</${cellTag}>
288
        </${rowTag}>
289
      `)}
290
    </${tableTag}>
291
  `;
292
};
293
```
294

295
## Types
296

297
```typescript { .api }
298
interface StaticValue {
299
  /** The value to interpolate as-is into the template */
300
  _$litStatic$: string;
301
  /** Brand to prevent JSON injection attacks */
302
  r: typeof brand;
303
}
304

305
interface TemplateResult<T extends ResultType = ResultType> {
306
  readonly strings: TemplateStringsArray;
307
  readonly values: unknown[];
308
}
309
```
310

311
## Import Patterns
312

313
```typescript
314
// Static template functions (enhanced versions)
315
import { html, svg, mathml } from 'lit-html/static.js';
316

317
// Static value creation
318
import { literal, unsafeStatic } from 'lit-html/static.js';
319

320
// Template wrapper utility
321
import { withStatic } from 'lit-html/static.js';
322

323
// Core functions for wrapping
324
import { html as coreHtml } from 'lit-html';
325

326
// Example usage
327
const tagName = literal`div`;
328
const template = html`<${tagName}>Content</${tagName}>`;
329
```
330

331
## Security Considerations
332

333
- **unsafeStatic**: Only use with trusted content. Untrusted input can lead to XSS vulnerabilities
334
- **literal**: Safe to use as it only accepts template literals from source code
335
- **Static values**: Changes cause complete re-renders, so use for truly static content
336
- **Validation**: Always validate dynamic input before passing to unsafeStatic