UNPKG

14.5 kBTypeScriptView Raw
1// https://htmx.org/reference/#api
2
3/**
4 * This method adds a class to the given element.
5 *
6 * https://htmx.org/api/#addClass
7 *
8 * @param elt the element to add the class to
9 * @param clazz the class to add
10 * @param delay the delay (in milliseconds before class is added)
11 */
12export function addClass(elt: Element, clazz: string, delay?: number): void;
13
14/**
15 * Issues an htmx-style AJAX request
16 *
17 * https://htmx.org/api/#ajax
18 *
19 * @param verb 'GET', 'POST', etc.
20 * @param path the URL path to make the AJAX
21 * @param element the element to target (defaults to the **body**)
22 * @returns Promise that resolves immediately if no request is sent, or when the request is complete
23 */
24export function ajax(verb: string, path: string, element: Element): Promise<void>;
25
26/**
27 * Issues an htmx-style AJAX request
28 *
29 * https://htmx.org/api/#ajax
30 *
31 * @param verb 'GET', 'POST', etc.
32 * @param path the URL path to make the AJAX
33 * @param selector a selector for the target
34 * @returns Promise that resolves immediately if no request is sent, or when the request is complete
35 */
36export function ajax(verb: string, path: string, selector: string): Promise<void>;
37
38/**
39 * Issues an htmx-style AJAX request
40 *
41 * https://htmx.org/api/#ajax
42 *
43 * @param verb 'GET', 'POST', etc.
44 * @param path the URL path to make the AJAX
45 * @param context a context object that contains any of the following
46 * @returns Promise that resolves immediately if no request is sent, or when the request is complete
47 */
48export function ajax(
49 verb: string,
50 path: string,
51 context: Partial<{ source: any; event: any; handler: any; target: any; swap: any; values: any; headers: any; select: any }>
52): Promise<void>;
53
54/**
55 * Finds the closest matching element in the given elements parentage, inclusive of the element
56 *
57 * https://htmx.org/api/#closest
58 *
59 * @param elt the element to find the selector from
60 * @param selector the selector to find
61 */
62export function closest(elt: Element, selector: string): Element | null;
63
64/**
65 * A property holding the configuration htmx uses at runtime.
66 *
67 * Note that using a [meta tag](https://htmx.org/docs/#config) is the preferred mechanism for setting these properties.
68 *
69 * https://htmx.org/api/#config
70 */
71export var config: HtmxConfig;
72
73/**
74 * A property used to create new [Server Sent Event](https://htmx.org/docs/#sse) sources. This can be updated to provide custom SSE setup.
75 *
76 * https://htmx.org/api/#createEventSource
77 */
78export var createEventSource: (url: string) => EventSource;
79
80/**
81 * A property used to create new [WebSocket](https://htmx.org/docs/#websockets). This can be updated to provide custom WebSocket setup.
82 *
83 * https://htmx.org/api/#createWebSocket
84 */
85export var createWebSocket: (url: string) => WebSocket;
86
87/**
88 * Defines a new htmx [extension](https://htmx.org/extensions).
89 *
90 * https://htmx.org/api/#defineExtension
91 *
92 * @param name the extension name
93 * @param ext the extension definition
94 */
95export function defineExtension(name: string, ext: HtmxExtension): void;
96
97/**
98 * Finds an element matching the selector
99 *
100 * https://htmx.org/api/#find
101 *
102 * @param selector the selector to match
103 */
104export function find(selector: string): Element | null;
105
106/**
107 * Finds an element matching the selector
108 *
109 * https://htmx.org/api/#find
110 *
111 * @param elt the root element to find the matching element in, inclusive
112 * @param selector the selector to match
113 */
114export function find(elt: Element, selector: string): Element | null;
115
116/**
117 * Finds all elements matching the selector
118 *
119 * https://htmx.org/api/#findAll
120 *
121 * @param selector the selector to match
122 */
123export function findAll(selector: string): NodeListOf<Element>;
124
125/**
126 * Finds all elements matching the selector
127 *
128 * https://htmx.org/api/#findAll
129 *
130 * @param elt the root element to find the matching elements in, inclusive
131 * @param selector the selector to match
132 */
133export function findAll(elt: Element, selector: string): NodeListOf<Element>;
134
135/**
136 * Log all htmx events, useful for debugging.
137 *
138 * https://htmx.org/api/#logAll
139 */
140export function logAll(): void;
141
142/**
143 * The logger htmx uses to log with
144 *
145 * https://htmx.org/api/#logger
146 */
147export var logger: (elt: Element, eventName: string, detail: any) => void | null;
148
149/**
150 * Removes an event listener from an element
151 *
152 * https://htmx.org/api/#off
153 *
154 * @param eventName the event name to remove the listener from
155 * @param listener the listener to remove
156 */
157export function off(eventName: string, listener: (evt: Event) => void): (evt: Event) => void;
158
159/**
160 * Removes an event listener from an element
161 *
162 * https://htmx.org/api/#off
163 *
164 * @param target the element to remove the listener from
165 * @param eventName the event name to remove the listener from
166 * @param listener the listener to remove
167 */
168export function off(target: string, eventName: string, listener: (evt: Event) => void): (evt: Event) => void;
169
170/**
171 * Adds an event listener to an element
172 *
173 * https://htmx.org/api/#on
174 *
175 * @param eventName the event name to add the listener for
176 * @param listener the listener to add
177 */
178export function on(eventName: string, listener: (evt: Event) => void): (evt: Event) => void;
179
180/**
181 * Adds an event listener to an element
182 *
183 * https://htmx.org/api/#on
184 *
185 * @param target the element to add the listener to
186 * @param eventName the event name to add the listener for
187 * @param listener the listener to add
188 */
189export function on(target: string, eventName: string, listener: (evt: Event) => void): (evt: Event) => void;
190
191/**
192 * Adds a callback for the **htmx:load** event. This can be used to process new content, for example initializing the content with a javascript library
193 *
194 * https://htmx.org/api/#onLoad
195 *
196 * @param callback the callback to call on newly loaded content
197 */
198export function onLoad(callback: (element: Element) => void): void;
199
200/**
201 * Parses an interval string consistent with the way htmx does. Useful for plugins that have timing-related attributes.
202 *
203 * Caution: Accepts an int followed by either **s** or **ms**. All other values use **parseFloat**
204 *
205 * https://htmx.org/api/#parseInterval
206 *
207 * @param str timing string
208 */
209export function parseInterval(str: string): number;
210
211/**
212 * Processes new content, enabling htmx behavior. This can be useful if you have content that is added to the DOM outside of the normal htmx request cycle but still want htmx attributes to work.
213 *
214 * https://htmx.org/api/#process
215 *
216 * @param element element to process
217 */
218export function process(element: Element): void;
219
220/**
221 * Removes an element from the DOM
222 *
223 * https://htmx.org/api/#remove
224 *
225 * @param elt element to remove
226 * @param delay the delay (in milliseconds before element is removed)
227 */
228export function remove(elt: Element, delay?: number): void;
229
230/**
231 * Removes a class from the given element
232 *
233 * https://htmx.org/api/#removeClass
234 *
235 * @param elt element to remove the class from
236 * @param clazz the class to remove
237 * @param delay the delay (in milliseconds before class is removed)
238 */
239export function removeClass(elt: Element, clazz: string, delay?: number): void;
240
241/**
242 * Removes the given extension from htmx
243 *
244 * https://htmx.org/api/#removeExtension
245 *
246 * @param name the name of the extension to remove
247 */
248export function removeExtension(name: string): void;
249
250/**
251 * Takes the given class from its siblings, so that among its siblings, only the given element will have the class.
252 *
253 * https://htmx.org/api/#takeClass
254 *
255 * @param elt the element that will take the class
256 * @param clazz the class to take
257 */
258export function takeClass(elt: Element, clazz: string): void;
259
260/**
261 * Toggles the given class on an element
262 *
263 * https://htmx.org/api/#toggleClass
264 *
265 * @param elt the element to toggle the class on
266 * @param clazz the class to toggle
267 */
268export function toggleClass(elt: Element, clazz: string): void;
269
270/**
271 * Triggers a given event on an element
272 *
273 * https://htmx.org/api/#trigger
274 *
275 * @param elt the element to trigger the event on
276 * @param name the name of the event to trigger
277 * @param detail details for the event
278 */
279export function trigger(elt: Element, name: string, detail: any): void;
280
281/**
282 * Returns the input values that would resolve for a given element via the htmx value resolution mechanism
283 *
284 * https://htmx.org/api/#values
285 *
286 * @param elt the element to resolve values on
287 * @param requestType the request type (e.g. **get** or **post**) non-GET's will include the enclosing form of the element. Defaults to **post**
288 */
289export function values(elt: Element, requestType?: string): any;
290
291export const version: string;
292
293export interface HtmxConfig {
294 /**
295 * The attributes to settle during the settling phase.
296 * @default ["class", "style", "width", "height"]
297 */
298 attributesToSettle?: ["class", "style", "width", "height"] | string[];
299 /**
300 * If the focused element should be scrolled into view.
301 * @default false
302 */
303 defaultFocusScroll?: boolean;
304 /**
305 * The default delay between completing the content swap and settling attributes.
306 * @default 20
307 */
308 defaultSettleDelay?: number;
309 /**
310 * The default delay between receiving a response from the server and doing the swap.
311 * @default 0
312 */
313 defaultSwapDelay?: number;
314 /**
315 * The default swap style to use if **[hx-swap](https://htmx.org/attributes/hx-swap)** is omitted.
316 * @default "innerHTML"
317 */
318 defaultSwapStyle?: "innerHTML" | string;
319 /**
320 * The number of pages to keep in **localStorage** for history support.
321 * @default 10
322 */
323 historyCacheSize?: number;
324 /**
325 * Whether or not to use history.
326 * @default true
327 */
328 historyEnabled?: boolean;
329 /**
330 * If true, htmx will inject a small amount of CSS into the page to make indicators invisible unless the **htmx-indicator** class is present.
331 * @default true
332 */
333 includeIndicatorStyles?: boolean;
334 /**
335 * The class to place on indicators when a request is in flight.
336 * @default "htmx-indicator"
337 */
338 indicatorClass?: "htmx-indicator" | string;
339 /**
340 * The class to place on triggering elements when a request is in flight.
341 * @default "htmx-request"
342 */
343 requestClass?: "htmx-request" | string;
344 /**
345 * The class to temporarily place on elements that htmx has added to the DOM.
346 * @default "htmx-added"
347 */
348 addedClass?: "htmx-added" | string;
349 /**
350 * The class to place on target elements when htmx is in the settling phase.
351 * @default "htmx-settling"
352 */
353 settlingClass?: "htmx-settling" | string;
354 /**
355 * The class to place on target elements when htmx is in the swapping phase.
356 * @default "htmx-swapping"
357 */
358 swappingClass?: "htmx-swapping" | string;
359 /**
360 * Allows the use of eval-like functionality in htmx, to enable **hx-vars**, trigger conditions & script tag evaluation. Can be set to **false** for CSP compatibility.
361 * @default true
362 */
363 allowEval?: boolean;
364 /**
365 * Use HTML template tags for parsing content from the server. This allows you to use Out of Band content when returning things like table rows, but it is *not* IE11 compatible.
366 * @default false
367 */
368 useTemplateFragments?: boolean;
369 /**
370 * Allow cross-site Access-Control requests using credentials such as cookies, authorization headers or TLS client certificates.
371 * @default false
372 */
373 withCredentials?: boolean;
374 /**
375 * The default implementation of **getWebSocketReconnectDelay** for reconnecting after unexpected connection loss by the event code **Abnormal Closure**, **Service Restart** or **Try Again Later**.
376 * @default "full-jitter"
377 */
378 wsReconnectDelay?: "full-jitter" | string | ((retryCount: number) => number);
379 // following don't appear in the docs
380 /** @default false */
381 refreshOnHistoryMiss?: boolean;
382 /** @default 0 */
383 timeout?: number;
384 /** @default "[hx-disable], [data-hx-disable]" */
385 disableSelector?: "[hx-disable], [data-hx-disable]" | string;
386 /** @default "smooth" */
387 scrollBehavior?: "smooth" | "auto";
388 /**
389 * If set to false, disables the interpretation of script tags.
390 * @default true
391 */
392 allowScriptTags?: boolean;
393 /**
394 * If set to true, disables htmx-based requests to non-origin hosts.
395 * @default false
396 */
397 selfRequestsOnly?: boolean;
398 /**
399 * Whether or not the target of a boosted element is scrolled into the viewport.
400 * @default true
401 */
402 scrollIntoViewOnBoost?: boolean;
403 /**
404 * If set, the nonce will be added to inline scripts.
405 * @default ''
406 */
407 inlineScriptNonce?: string;
408 /**
409 * The type of binary data being received over the WebSocket connection
410 * @default 'blob'
411 */
412 wsBinaryType?: 'blob' | 'arraybuffer';
413 /**
414 * If set to true htmx will include a cache-busting parameter in GET requests to avoid caching partial responses by the browser
415 * @default false
416 */
417 getCacheBusterParam?: boolean;
418 /**
419 * If set to true, htmx will use the View Transition API when swapping in new content.
420 * @default false
421 */
422 globalViewTransitions?: boolean;
423 /**
424 * htmx will format requests with these methods by encoding their parameters in the URL, not the request body
425 * @default ["get"]
426 */
427 methodsThatUseUrlParams?: ('get' | 'head' | 'post' | 'put' | 'delete' | 'connect' | 'options' | 'trace' | 'patch' )[];
428 /**
429 * If set to true htmx will not update the title of the document when a title tag is found in new content
430 * @default false
431 */
432 ignoreTitle:? boolean;
433 /**
434 * The cache to store evaluated trigger specifications into.
435 * You may define a simple object to use a never-clearing cache, or implement your own system using a [proxy object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
436 * @default null
437 */
438 triggerSpecsCache?: {[trigger: string]: HtmxTriggerSpecification[]};
439}
440
441/**
442 * https://htmx.org/extensions/#defining
443 */
444export interface HtmxExtension {
445 onEvent?: (name: string, evt: CustomEvent) => any;
446 transformResponse?: (text: any, xhr: XMLHttpRequest, elt: any) => any;
447 isInlineSwap?: (swapStyle: any) => any;
448 handleSwap?: (swapStyle: any, target: any, fragment: any, settleInfo: any) => any;
449 encodeParameters?: (xhr: XMLHttpRequest, parameters: any, elt: any) => any;
450}
451
\No newline at end of file