tessl/npm-htmx-org
JavaScript library that extends HTML with AJAX, CSS Transitions, WebSockets, and Server-Sent Events through declarative attributes
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-htmx-org@2.0.00
# HTMX
1
2
HTMX is a JavaScript library that extends HTML with modern web interactions through declarative attributes, providing access to AJAX, CSS Transitions, WebSockets, and Server-Sent Events without requiring custom JavaScript code. It enables progressive enhancement by completing HTML as a true hypertext system.
3
4
## Package Information
5
6
- **Package Name**: htmx.org
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install htmx.org`
10
11
## Core Imports
12
13
**Browser Script Tag:**
14
```html
15
<script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js"></script>
16
```
17
18
**ES Modules:**
19
```javascript
20
import htmx from "htmx.org";
21
```
22
23
**CommonJS:**
24
```javascript
25
const htmx = require("htmx.org");
26
```
27
28
**AMD:**
29
```javascript
30
require(["htmx.org"], function(htmx) {
31
// use htmx
32
});
33
```
34
35
## Basic Usage
36
37
```html
38
<!DOCTYPE html>
39
<html>
40
<head>
41
<script src="https://cdn.jsdelivr.net/npm/htmx.org@2.0.6/dist/htmx.min.js"></script>
42
</head>
43
<body>
44
<!-- Simple AJAX request triggered by button click -->
45
<button hx-get="/api/data" hx-target="#content">
46
Load Data
47
</button>
48
<div id="content">
49
<!-- Response will be inserted here -->
50
</div>
51
52
<!-- Form submission with AJAX -->
53
<form hx-post="/api/users" hx-target="#result">
54
<input type="text" name="name" placeholder="Name">
55
<button type="submit">Create User</button>
56
</form>
57
<div id="result"></div>
58
</body>
59
</html>
60
```
61
62
## Architecture
63
64
HTMX extends HTML through several key components:
65
66
- **Attribute System**: HTML attributes that declaratively specify behavior (hx-get, hx-post, hx-target, etc.)
67
- **Event System**: Rich event lifecycle with custom events for request/response handling
68
- **Swap System**: Flexible content replacement strategies (innerHTML, outerHTML, beforeend, etc.)
69
- **Request Processing**: Automatic form data collection, header management, and response handling
70
- **Extension System**: Plugin architecture for custom behaviors and integrations
71
- **Configuration**: Global settings for default behaviors, timeouts, CSS classes, and more
72
73
## Capabilities
74
75
### Event Processing
76
77
Core event handling and lifecycle management for processing new content and managing user interactions.
78
79
```javascript { .api }
80
// Register callback for newly loaded content
81
function onLoad(callback: (elt: Node) => void): EventListener;
82
83
// Process new content to enable htmx behavior
84
function process(elt: Element | string): void;
85
86
// Add event listeners with htmx-aware handling
87
function on(target: EventTarget | string, event: string, listener: EventListener, options?: any): EventListener;
88
89
// Remove event listeners
90
function off(target: EventTarget | string, event: string, listener?: EventListener): EventListener;
91
92
// Trigger events on elements
93
function trigger(elt: EventTarget | string, eventName: string, detail?: any): boolean;
94
```
95
96
[Event Processing](./event-processing.md)
97
98
### AJAX Requests
99
100
Programmatic AJAX request functionality for issuing htmx-style requests with full configuration options.
101
102
```javascript { .api }
103
// Issue htmx-style AJAX request
104
function ajax(verb: HttpVerb, path: string, context: Element | string | HtmxAjaxHelperContext): Promise<void>;
105
106
type HttpVerb = "get" | "head" | "post" | "put" | "delete" | "connect" | "options" | "trace" | "patch";
107
108
interface HtmxAjaxHelperContext {
109
source?: Element | string;
110
event?: Event;
111
handler?: HtmxAjaxHandler;
112
target?: Element | string;
113
swap?: HtmxSwapStyle;
114
values?: any | FormData;
115
headers?: Record<string, string>;
116
select?: string;
117
}
118
```
119
120
[AJAX Requests](./ajax-requests.md)
121
122
### DOM Querying
123
124
Utility functions for finding and querying DOM elements with htmx-aware selectors.
125
126
```javascript { .api }
127
// Find single element matching selector
128
function find(eltOrSelector: ParentNode | string, selector?: string): Element | null;
129
130
// Find all elements matching selector
131
function findAll(eltOrSelector: ParentNode | string, selector?: string): NodeListOf<Element>;
132
133
// Find closest matching element in parentage
134
function closest(elt: Element | string, selector: string): Element | null;
135
136
// Get input values for element using htmx resolution
137
function values(elt: Element, type: HttpVerb): Object;
138
```
139
140
[DOM Querying](./dom-querying.md)
141
142
### DOM Manipulation
143
144
Functions for manipulating DOM elements including class management, content swapping, and element removal.
145
146
```javascript { .api }
147
// Remove element with optional delay
148
function remove(elt: Node, delay?: number): void;
149
150
// Add CSS class to element
151
function addClass(elt: Element | string, clazz: string, delay?: number): void;
152
153
// Remove CSS class from element
154
function removeClass(node: Node | string, clazz: string, delay?: number): void;
155
156
// Toggle CSS class on element
157
function toggleClass(elt: Element | string, clazz: string): void;
158
159
// Take class from siblings (ensure only this element has class)
160
function takeClass(elt: Node | string, clazz: string): void;
161
162
// Perform complete content swap with transitions
163
function swap(target: string | Element, content: string, swapSpec: HtmxSwapSpecification, swapOptions?: SwapOptions): void;
164
```
165
166
[DOM Manipulation](./dom-manipulation.md)
167
168
### Extension System
169
170
Plugin architecture for extending htmx functionality with custom behaviors and integrations.
171
172
```javascript { .api }
173
// Register new extension
174
function defineExtension(name: string, extension: Partial<HtmxExtension>): void;
175
176
// Remove registered extension
177
function removeExtension(name: string): void;
178
179
interface HtmxExtension {
180
init: (api: any) => void;
181
onEvent: (name: string, event: CustomEvent) => boolean;
182
transformResponse: (text: string, xhr: XMLHttpRequest, elt: Element) => string;
183
isInlineSwap: (swapStyle: HtmxSwapStyle) => boolean;
184
handleSwap: (swapStyle: HtmxSwapStyle, target: Node, fragment: Node, settleInfo: HtmxSettleInfo) => boolean | Node[];
185
encodeParameters: (xhr: XMLHttpRequest, parameters: FormData, elt: Node) => any | string | null;
186
getSelectors: () => string[] | null;
187
}
188
```
189
190
[Extension System](./extension-system.md)
191
192
### Configuration
193
194
Global configuration object controlling all aspects of htmx behavior including defaults, timeouts, CSS classes, and security settings.
195
196
```javascript { .api }
197
// Main configuration object
198
const config: {
199
// History & Navigation
200
historyEnabled: boolean;
201
historyCacheSize: number;
202
refreshOnHistoryMiss: boolean;
203
scrollIntoViewOnBoost: boolean;
204
205
// Swap Behavior
206
defaultSwapStyle: HtmxSwapStyle;
207
defaultSwapDelay: number;
208
defaultSettleDelay: number;
209
globalViewTransitions: boolean;
210
211
// CSS Classes
212
indicatorClass: string;
213
requestClass: string;
214
addedClass: string;
215
settlingClass: string;
216
swappingClass: string;
217
218
// Security
219
allowEval: boolean;
220
allowScriptTags: boolean;
221
selfRequestsOnly: boolean;
222
223
// Request handling
224
withCredentials: boolean;
225
timeout: number;
226
methodsThatUseUrlParams: HttpVerb[];
227
228
// WebSocket
229
wsReconnectDelay: string | function;
230
wsBinaryType: BinaryType;
231
232
// Response handling
233
responseHandling: HtmxResponseHandlingConfig[];
234
};
235
236
type HtmxSwapStyle = "innerHTML" | "outerHTML" | "beforebegin" | "afterbegin" | "beforeend" | "afterend" | "delete" | "none" | string;
237
```
238
239
[Configuration](./configuration.md)
240
241
### Debugging & Utilities
242
243
Tools for debugging htmx behavior and utility functions for common operations.
244
245
```javascript { .api }
246
// Enable logging of all htmx events
247
function logAll(): void;
248
249
// Disable htmx event logging
250
function logNone(): void;
251
252
// Custom logger for htmx events
253
let logger: any;
254
255
// Parse timing intervals (e.g., "1s", "500ms")
256
function parseInterval(str: string): number | undefined;
257
258
// Current htmx version
259
const version: string;
260
261
// Location proxy for page reloads
262
const location: Location;
263
```
264
265
[Debugging & Utilities](./debugging-utilities.md)
266
267
## Global Types
268
269
```javascript { .api }
270
// HTTP methods supported by htmx
271
type HttpVerb = "get" | "head" | "post" | "put" | "delete" | "connect" | "options" | "trace" | "patch";
272
273
// Content swap styles
274
type HtmxSwapStyle = "innerHTML" | "outerHTML" | "beforebegin" | "afterbegin" | "beforeend" | "afterend" | "delete" | "none" | string;
275
276
// Complete swap specification
277
interface HtmxSwapSpecification {
278
swapStyle: HtmxSwapStyle;
279
swapDelay: number;
280
settleDelay: number;
281
transition?: boolean;
282
ignoreTitle?: boolean;
283
head?: string;
284
scroll?: "top" | "bottom" | number;
285
scrollTarget?: string;
286
show?: string;
287
showTarget?: string;
288
focusScroll?: boolean;
289
}
290
291
// Swap operation options
292
interface SwapOptions {
293
select?: string;
294
selectOOB?: string;
295
eventInfo?: any;
296
anchor?: string;
297
contextElement?: Element;
298
afterSwapCallback?: swapCallback;
299
afterSettleCallback?: swapCallback;
300
beforeSwapCallback?: swapCallback;
301
title?: string;
302
historyRequest?: boolean;
303
}
304
305
type swapCallback = () => any;
306
307
// Trigger specification for events
308
interface HtmxTriggerSpecification {
309
trigger: string;
310
pollInterval?: number;
311
eventFilter?: ConditionalFunction;
312
changed?: boolean;
313
once?: boolean;
314
consume?: boolean;
315
delay?: number;
316
from?: string;
317
target?: string;
318
throttle?: number;
319
queue?: string;
320
root?: string;
321
threshold?: string;
322
}
323
324
// Request configuration
325
interface HtmxRequestConfig {
326
boosted: boolean;
327
useUrlParams: boolean;
328
formData: FormData;
329
parameters: any;
330
unfilteredFormData: FormData;
331
unfilteredParameters: any;
332
headers: HtmxHeaderSpecification;
333
elt: Element;
334
target: Element;
335
verb: HttpVerb;
336
errors: HtmxElementValidationError[];
337
withCredentials: boolean;
338
timeout: number;
339
path: string;
340
triggeringEvent: Event;
341
}
342
343
// Response information
344
interface HtmxResponseInfo {
345
xhr: XMLHttpRequest;
346
target: Element;
347
requestConfig: HtmxRequestConfig;
348
etc: HtmxAjaxEtc;
349
boosted: boolean;
350
select: string;
351
pathInfo: {
352
requestPath: string;
353
finalRequestPath: string;
354
responsePath: string | null;
355
anchor: string;
356
};
357
failed?: boolean;
358
successful?: boolean;
359
keepIndicators?: boolean;
360
}
361
362
// Validation error
363
interface HtmxElementValidationError {
364
elt: Element;
365
message: string;
366
validity: ValidityState;
367
}
368
369
// HTTP headers
370
type HtmxHeaderSpecification = Record<string, string>;
371
372
// Response handling configuration
373
interface HtmxResponseHandlingConfig {
374
code?: string;
375
swap: boolean;
376
error?: boolean;
377
ignoreTitle?: boolean;
378
select?: string;
379
target?: string;
380
swapOverride?: string;
381
event?: string;
382
}
383
384
// Settlement information
385
interface HtmxSettleInfo {
386
tasks: HtmxSettleTask[];
387
elts: Element[];
388
title?: string;
389
}
390
391
type HtmxSettleTask = () => void;
392
393
// AJAX handler function
394
type HtmxAjaxHandler = (elt: Element, responseInfo: HtmxResponseInfo) => any;
395
396
// Conditional function for event filtering
397
type ConditionalFunction = ((this: Node, evt: Event) => boolean) & {
398
source: string;
399
};
400
401
// Additional AJAX context
402
interface HtmxAjaxEtc {
403
returnPromise?: boolean;
404
handler?: HtmxAjaxHandler;
405
select?: string;
406
targetOverride?: Element;
407
swapOverride?: HtmxSwapStyle;
408
headers?: Record<string, string>;
409
values?: any | FormData;
410
credentials?: boolean;
411
timeout?: number;
412
}
413
414
// Before swap event details
415
interface HtmxBeforeSwapDetails extends HtmxResponseInfo {
416
shouldSwap: boolean;
417
serverResponse: any;
418
isError: boolean;
419
ignoreTitle: boolean;
420
selectOverride: string;
421
swapOverride: string;
422
}
423
```