UNPKG

11.3 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 */
23export function ajax(verb: string, path: string, element: Element): void;
24
25/**
26 * Issues an htmx-style AJAX request
27 *
28 * https://htmx.org/api/#ajax
29 *
30 * @param verb 'GET', 'POST', etc.
31 * @param path the URL path to make the AJAX
32 * @param selector a selector for the target
33 */
34export function ajax(verb: string, path: string, selector: string): void;
35
36/**
37 * Issues an htmx-style AJAX request
38 *
39 * https://htmx.org/api/#ajax
40 *
41 * @param verb 'GET', 'POST', etc.
42 * @param path the URL path to make the AJAX
43 * @param context a context object that contains any of the following
44 */
45export function ajax(
46 verb: string,
47 path: string,
48 context: Partial<{ source: any; event: any; handler: any; target: any; values: any; headers: any }>
49): void;
50
51/**
52 * Finds the closest matching element in the given elements parentage, inclusive of the element
53 *
54 * https://htmx.org/api/#closest
55 *
56 * @param elt the element to find the selector from
57 * @param selector the selector to find
58 */
59export function closest(elt: Element, selector: string): Element | null;
60
61/**
62 * A property holding the configuration htmx uses at runtime.
63 *
64 * Note that using a [meta tag](https://htmx.org/docs/#config) is the preferred mechanism for setting these properties.
65 *
66 * https://htmx.org/api/#config
67 */
68export var config: HtmxConfig;
69
70/**
71 * A property used to create new [Server Sent Event](https://htmx.org/docs/#sse) sources. This can be updated to provide custom SSE setup.
72 *
73 * https://htmx.org/api/#createEventSource
74 */
75export var createEventSource: (url: string) => EventSource;
76
77/**
78 * A property used to create new [WebSocket](https://htmx.org/docs/#websockets). This can be updated to provide custom WebSocket setup.
79 *
80 * https://htmx.org/api/#createWebSocket
81 */
82export var createWebSocket: (url: string) => WebSocket;
83
84/**
85 * Defines a new htmx [extension](https://htmx.org/extensions).
86 *
87 * https://htmx.org/api/#defineExtension
88 *
89 * @param name the extension name
90 * @param ext the extension definition
91 */
92export function defineExtension(name: string, ext: HtmxExtension): void;
93
94/**
95 * Finds an element matching the selector
96 *
97 * https://htmx.org/api/#find
98 *
99 * @param selector the selector to match
100 */
101export function find(selector: string): Element | null;
102
103/**
104 * Finds an element matching the selector
105 *
106 * https://htmx.org/api/#find
107 *
108 * @param elt the root element to find the matching element in, inclusive
109 * @param selector the selector to match
110 */
111export function find(elt: Element, selector: string): Element | null;
112
113/**
114 * Finds all elements matching the selector
115 *
116 * https://htmx.org/api/#findAll
117 *
118 * @param selector the selector to match
119 */
120export function findAll(selector: string): NodeListOf<Element>;
121
122/**
123 * Finds all elements matching the selector
124 *
125 * https://htmx.org/api/#findAll
126 *
127 * @param elt the root element to find the matching elements in, inclusive
128 * @param selector the selector to match
129 */
130export function findAll(elt: Element, selector: string): NodeListOf<Element>;
131
132/**
133 * Log all htmx events, useful for debugging.
134 *
135 * https://htmx.org/api/#logAll
136 */
137export function logAll(): void;
138
139/**
140 * The logger htmx uses to log with
141 *
142 * https://htmx.org/api/#logger
143 */
144export var logger: (elt: Element, eventName: string, detail: any) => void | null;
145
146/**
147 * Removes an event listener from an element
148 *
149 * https://htmx.org/api/#off
150 *
151 * @param eventName the event name to remove the listener from
152 * @param listener the listener to remove
153 */
154export function off(eventName: string, listener: (evt: Event) => void): (evt: Event) => void;
155
156/**
157 * Removes an event listener from an element
158 *
159 * https://htmx.org/api/#off
160 *
161 * @param target the element to remove the listener from
162 * @param eventName the event name to remove the listener from
163 * @param listener the listener to remove
164 */
165export function off(target: string, eventName: string, listener: (evt: Event) => void): (evt: Event) => void;
166
167/**
168 * Adds an event listener to an element
169 *
170 * https://htmx.org/api/#on
171 *
172 * @param eventName the event name to add the listener for
173 * @param listener the listener to add
174 */
175export function on(eventName: string, listener: (evt: Event) => void): (evt: Event) => void;
176
177/**
178 * Adds an event listener to an element
179 *
180 * https://htmx.org/api/#on
181 *
182 * @param target the element to add the listener to
183 * @param eventName the event name to add the listener for
184 * @param listener the listener to add
185 */
186export function on(target: string, eventName: string, listener: (evt: Event) => void): (evt: Event) => void;
187
188/**
189 * 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
190 *
191 * https://htmx.org/api/#onLoad
192 *
193 * @param callback the callback to call on newly loaded content
194 */
195export function onLoad(callback: (element: Element) => void): void;
196
197/**
198 * Parses an interval string consistent with the way htmx does. Useful for plugins that have timing-related attributes.
199 *
200 * Caution: Accepts an int followed by either **s** or **ms**. All other values use **parseFloat**
201 *
202 * https://htmx.org/api/#parseInterval
203 *
204 * @param str timing string
205 */
206export function parseInterval(str: string): number;
207
208/**
209 * 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.
210 *
211 * https://htmx.org/api/#process
212 *
213 * @param element element to process
214 */
215export function process(element: Element): void;
216
217/**
218 * Removes an element from the DOM
219 *
220 * https://htmx.org/api/#remove
221 *
222 * @param elt element to remove
223 * @param delay the delay (in milliseconds before element is removed)
224 */
225export function remove(elt: Element, delay?: number): void;
226
227/**
228 * Removes a class from the given element
229 *
230 * https://htmx.org/api/#removeClass
231 *
232 * @param elt element to remove the class from
233 * @param clazz the class to remove
234 * @param delay the delay (in milliseconds before class is removed)
235 */
236export function removeClass(elt: Element, clazz: string, delay?: number): void;
237
238/**
239 * Removes the given extension from htmx
240 *
241 * https://htmx.org/api/#removeExtension
242 *
243 * @param name the name of the extension to remove
244 */
245export function removeExtension(name: string): void;
246
247/**
248 * Takes the given class from its siblings, so that among its siblings, only the given element will have the class.
249 *
250 * https://htmx.org/api/#takeClass
251 *
252 * @param elt the element that will take the class
253 * @param clazz the class to take
254 */
255export function takeClass(elt: Element, clazz: string): void;
256
257/**
258 * Toggles the given class on an element
259 *
260 * https://htmx.org/api/#toggleClass
261 *
262 * @param elt the element to toggle the class on
263 * @param clazz the class to toggle
264 */
265export function toggleClass(elt: Element, clazz: string): void;
266
267/**
268 * Triggers a given event on an element
269 *
270 * https://htmx.org/api/#trigger
271 *
272 * @param elt the element to trigger the event on
273 * @param name the name of the event to trigger
274 * @param detail details for the event
275 */
276export function trigger(elt: Element, name: string, detail: any): void;
277
278/**
279 * Returns the input values that would resolve for a given element via the htmx value resolution mechanism
280 *
281 * https://htmx.org/api/#values
282 *
283 * @param elt the element to resolve values on
284 * @param requestType the request type (e.g. **get** or **post**) non-GET's will include the enclosing form of the element. Defaults to **post**
285 */
286export function values(elt: Element, requestType?: string): any;
287
288export const version: string;
289
290export interface HtmxConfig {
291 /** array of strings: the attributes to settle during the settling phase */
292 attributesToSettle?: ["class", "style", "width", "height"] | string[];
293 /** the default delay between completing the content swap and settling attributes */
294 defaultSettleDelay?: number;
295 /** the default delay between receiving a response from the server and doing the swap */
296 defaultSwapDelay?: number;
297 /** the default swap style to use if **[hx-swap](https://htmx.org/attributes/hx-swap)** is omitted */
298 defaultSwapStyle?: "innerHTML" | string;
299 /** the number of pages to keep in **localStorage** for history support */
300 historyCacheSize?: number;
301 /** whether or not to use history */
302 historyEnabled?: boolean;
303 /** if true, htmx will inject a small amount of CSS into the page to make indicators invisible unless the **htmx-indicator** class is present */
304 includeIndicatorStyles?: boolean;
305 /** the class to place on indicators when a request is in flight */
306 indicatorClass?: "htmx-indicator" | string;
307 /** the class to place on triggering elements when a request is in flight */
308 requestClass?: "htmx-request" | string;
309 /** the class to temporarily place on elements that htmx has added to the DOM */
310 addedClass?: "htmx-added" | string;
311 /** the class to place on target elements when htmx is in the settling phase */
312 settlingClass?: "htmx-settling" | string;
313 /** the class to place on target elements when htmx is in the swapping phase */
314 swappingClass?: "htmx-swapping" | string;
315 /** 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 */
316 allowEval?: boolean;
317 /** 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. */
318 useTemplateFragments?: boolean;
319 /** allow cross-site Access-Control requests using credentials such as cookies, authorization headers or TLS client certificates */
320 withCredentials?: boolean;
321 /** the default implementation of **getWebSocketReconnectDelay** for reconnecting after unexpected connection loss by the event code **Abnormal Closure**, **Service Restart** or **Try Again Later** */
322 wsReconnectDelay?: "full-jitter" | string | ((retryCount: number) => number);
323 // following don't appear in the docs
324 refreshOnHistoryMiss?: boolean;
325 timeout?: number;
326 disableSelector?: "[hx-disable], [data-hx-disable]" | string;
327 scrollBehavior?: "smooth";
328}
329
330/**
331 * https://htmx.org/extensions/#defining
332 */
333export interface HtmxExtension {
334 onEvent?: (name: string, evt: CustomEvent) => any;
335 transformResponse?: (text: any, xhr: XMLHttpRequest, elt: any) => any;
336 isInlineSwap?: (swapStyle: any) => any;
337 handleSwap?: (swapStyle: any, target: any, fragment: any, settleInfo: any) => any;
338 encodeParameters?: (xhr: XMLHttpRequest, parameters: any, elt: any) => any;
339}