0
# HTM (Hyperscript Tagged Markup)
1

2
HTM provides JSX-like syntax using tagged template literals for Virtual DOM creation, eliminating the need for transpilation. It's a lightweight library (under 600 bytes) that enables component-based user interfaces with any hyperscript-compatible renderer like React, Preact, or custom rendering functions.
3

4
## Package Information
5

6
- **Package Name**: htm
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Version**: 3.1.1
10
- **Installation**: `npm install htm`
11
- **Repository**: https://github.com/developit/htm
12
- **License**: Apache-2.0
13

14
## Core Imports
15

16
**ESM (preferred):**
17

18
```javascript
19
import htm from "htm";
20
// Create bound template function
21
const html = htm.bind(h); // where h is your hyperscript function
22
```
23

24
**CommonJS:**
25

26
```javascript
27
const htm = require("htm");
28
const html = htm.bind(h);
29
```
30

31
**UMD (browser):**
32

33
```html
34
<script src="https://unpkg.com/htm/dist/htm.umd.js"></script>
35
<script>
36
  const html = htm.bind(h);
37
</script>
38
```
39

40
## Basic Usage
41

42
```javascript
43
import htm from "htm";
44

45
// Your hyperscript function (h)
46
const h = (tag, props, ...children) => ({ tag, props, children });
47

48
// Bind HTM to your hyperscript function
49
const html = htm.bind(h);
50

51
// Use tagged template syntax
52
const vdom = html`
53
  <div class="container">
54
    <h1>Hello, ${name}!</h1>
55
    <button onclick=${handleClick}>Click me</button>
56
  </div>
57
`;
58

59
// Works with components
60
const MyComponent = ({ title }) => html`<h2>${title}</h2>`;
61
const app = html`<${MyComponent} title="Welcome" />`;
62

63
// Multiple root elements
64
const items = html`
65
  <li>Item 1</li>
66
  <li>Item 2</li>
67
  <li>Item 3</li>
68
`;
69
```
70

71
## Architecture
72

73
HTM consists of several key components:
74

75
- **Core Parser**: Tagged template literal parser that converts HTML-like syntax to hyperscript calls
76
- **Template Caching**: Performance optimization through template compilation caching
77
- **Framework Integrations**: Pre-configured variants for popular frameworks (Preact, React)
78
- **Build Variants**: Regular and mini versions for different bundle size requirements
79
- **Type System**: Full TypeScript support with generic type preservation
80

81
## Capabilities
82

83
### Core HTM Engine
84

85
The primary HTM function factory that creates tagged template functions bound to any hyperscript-compatible renderer.
86

87
```javascript { .api }
88
const htm: {
89
  bind<HResult>(
90
    h: (type: any, props: Record<string, any>, ...children: any[]) => HResult
91
  ): (strings: TemplateStringsArray, ...values: any[]) => HResult | HResult[];
92
};
93
```
94

95
**Key Features:**
96
- Template caching for performance
97
- Support for any hyperscript function pattern: `h(type, props, ...children)`
98
- Returns single elements or arrays for multiple root elements
99
- Full TypeScript generic support for type preservation
100

101
[Core HTM API](./core-htm.md)
102

103
### Preact Integration
104

105
Pre-configured HTM integration for Preact applications with optimized imports and type definitions.
106

107
```javascript { .api }
108
// From htm/preact
109
declare const html: (strings: TemplateStringsArray, ...values: any[]) => VNode;
110
declare function render(tree: VNode, parent: HTMLElement): void;
111
declare class Component { /* Preact Component class */ }
112
```
113

114
**Features:**
115
- Pre-bound `html` template function for Preact
116
- Direct re-exports of Preact's core functions
117
- Full hook integration via preact/hooks re-exports
118
- Standalone variant with all hooks included
119

120
[Preact Integration](./preact-integration.md)
121

122
### React Integration
123

124
Streamlined HTM integration for React applications with createElement binding.
125

126
```javascript { .api }
127
// From htm/react
128
declare const html: (strings: TemplateStringsArray, ...values: any[]) => React.ReactElement;
129
```
130

131
**Features:**
132
- Pre-bound `html` template function for React
133
- Automatic createElement binding
134
- Full React TypeScript support
135

136
[React Integration](./react-integration.md)
137

138
### Advanced Usage & Utilities
139

140
Advanced customization through custom hyperscript functions and build-time integrations.
141

142
**Use Cases:**
143
- Custom rendering backends (HTML strings, JSON structures, etc.)
144
- Build-time optimization with Babel plugins
145
- Framework integrations and adapters
146
- Performance profiling and analysis
147

148
[Advanced Usage](./advanced-usage.md)
149

150
## Template Syntax Features
151

152
HTM supports extensive HTML-like syntax features:
153

154
- **Standard HTML**: `<div class="foo">content</div>`
155
- **Self-closing tags**: `<img src="photo.jpg" />` or `<Component />`
156
- **Dynamic values**: `<div class=${className}>${content}</div>`  
157
- **Boolean attributes**: `<input disabled />` (becomes `disabled: true`)
158
- **Component interpolation**: `<${Component} prop="value" />`
159
- **Prop spreading**: `<div ...${props} additional="value" />`
160
- **Multiple root elements**: `<div>1</div><div>2</div>` (returns array)
161
- **Fragment syntax**: `<><child1/><child2/></>` 
162
- **Implicit closing**: `<div>content</>` (infers closing tag)
163
- **HTML comments**: `<!-- This is a comment -->`
164
- **Mixed quotes**: Both single and double quotes supported
165
- **Component end tags**: `<${Component}>children</${Component}>`
166

167
## Export Variants
168

169
HTM provides multiple export configurations for different use cases:
170

171
| Export Path | Purpose | Bundle Size |
172
|-------------|---------|--------------|
173
| `htm` | Core library | ~600 bytes |
174
| `htm/mini` | Size-optimized | ~400 bytes |
175
| `htm/preact` | Preact integration | Includes Preact |
176
| `htm/preact/standalone` | Preact + all hooks | Includes Preact + hooks |
177
| `htm/react` | React integration | Requires React |
178
179
All variants support multiple module formats (ESM, CommonJS, UMD) and include TypeScript definitions.
180

181
## Types
182

183
```typescript { .api }
184
// Core HTM type
185
interface HTM {
186
  bind<HResult>(
187
    h: (type: any, props: Record<string, any>, ...children: any[]) => HResult
188
  ): (strings: TemplateStringsArray, ...values: any[]) => HResult | HResult[];
189
}
190

191
// Template function signature
192
type TemplateFunction<T> = (
193
  strings: TemplateStringsArray,
194
  ...values: any[]
195
) => T | T[];
196

197
// Hyperscript function signature
198
type HyperscriptFunction<T> = (
199
  type: any,
200
  props: Record<string, any> | null,
201
  ...children: any[]
202
) => T;
203
```