1 | export interface ILazyLoadOptions {
|
2 | /**
|
3 | * The CSS selector of the elements to load lazily, which will be selected
|
4 | * as descendants of the `container` object.
|
5 |
|
6 | * @default ".lazy"
|
7 | */
|
8 | elements_selector?: string;
|
9 |
|
10 | /**
|
11 | * The scrolling container of the elements in the `elements_selector` option.
|
12 | *
|
13 | * @default document
|
14 | */
|
15 | container?: HTMLElement;
|
16 |
|
17 | /**
|
18 | * A number of pixels representing the outer distance off the scrolling area
|
19 | * from which to start loading the elements.
|
20 | * @default 300
|
21 | */
|
22 | threshold?: number;
|
23 |
|
24 | /**
|
25 | * Similar to `threshold`, but accepting multiple values and both `px` and `%`
|
26 | * units. It maps directly to the `rootMargin` property of IntersectionObserver,
|
27 | * so it must be a string with a syntax similar to the CSS `margin` property.
|
28 | * You can use it when you need to have different thresholds for the scrolling
|
29 | * area. It overrides `threshold` when passed.
|
30 | *
|
31 | * @default null
|
32 | *
|
33 | * @see https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin
|
34 | */
|
35 | thresholds?: string;
|
36 |
|
37 | /**
|
38 | * The name of the data attribute containing the element URL to load,
|
39 | * excluding the `"data-"` part.
|
40 | * E.g. if your data attribute is named `"data-src"`,
|
41 | * just pass `"src"`
|
42 | *
|
43 | * @default "src"
|
44 | */
|
45 | data_src?: string;
|
46 |
|
47 | /**
|
48 | * The name of the data attribute containing the image URL set to load,
|
49 | * in either img and source tags, excluding the "data-" part.
|
50 | * E.g. if your data attribute is named `"data-srcset"`,
|
51 | * just pass `"srcset"`
|
52 | *
|
53 | * @default "srcset"
|
54 | */
|
55 | data_srcset?: string;
|
56 |
|
57 | /**
|
58 | * The name of the data attribute containing the sizes attribute to use,
|
59 | * excluding the `"data-"` part.
|
60 | * E.g. if your data attribute is named `"data-sizes"`, just pass `"sizes"`
|
61 | *
|
62 | * @default "sizes"
|
63 | */
|
64 | data_sizes?: string;
|
65 |
|
66 | /**
|
67 | * The name of the data attribute containing the URL of `background-image`
|
68 | * to load lazily, excluding the `"data-"` part.
|
69 | * E.g. if your data attribute is named `"data-bg"`, just pass `"bg"`.
|
70 | * The attribute value must be a valid value for `background-image`,
|
71 | * including the `url()` part of the CSS instruction.
|
72 | *
|
73 | * @default "bg"
|
74 | */
|
75 | data_bg?: string;
|
76 |
|
77 | /**
|
78 | * The name of the data attribute containing the URL of `background-image`
|
79 | * to load lazily on HiDPI screens, excluding the `"data-"` part.
|
80 | * E.g. if your data attribute is named `"data-bg-hidpi"`, just pass `"bg-hidpi"`.
|
81 | * The attribute value must be a valid value for `background-image`,
|
82 | * including the `url()` part of the CSS instruction.
|
83 | *
|
84 | * @default "bg-hidpi"
|
85 | */
|
86 | data_bg_hidpi?: string;
|
87 |
|
88 | /**
|
89 | * The name of the data attribute containing the value of multiple `background-image`
|
90 | * to load lazily, excluding the `"data-"` part.
|
91 | * E.g. if your data attribute is named `"data-bg-multi"`, just pass `"bg-multi"`.
|
92 | * The attribute value must be a valid value for `background-image`,
|
93 | * including the `url()` part of the CSS instruction.
|
94 | *
|
95 | * @default "bg-multi"
|
96 | */
|
97 | data_bg_multi?: string;
|
98 |
|
99 | /**
|
100 | * The name of the data attribute containing the value of multiple `background-image`
|
101 | * to load lazily on HiDPI screens, excluding the `"data-"` part.
|
102 | * E.g. if your data attribute is named `"data-bg-multi-hidpi"`, just pass `"bg-multi-hidpi"`.
|
103 | * The attribute value must be a valid value for `background-image`,
|
104 | * including the `url()` part of the CSS instruction.
|
105 | *
|
106 | * @default "bg-multi-hidpi"
|
107 | */
|
108 | data_bg_multi_hidpi?: string;
|
109 |
|
110 | /**
|
111 | * The name of the data attribute containing the value of the background to
|
112 | * be applied with image-set, excluding the `"data-"` part.
|
113 | * E.g. if your data attribute is named `"data-bg-set"`, just pass `"bg-set"`.
|
114 | * The attribute value must be what goes inside the `image-set` CSS function.
|
115 | * You can separate values with a pipe (`|`) character to have
|
116 | * multiple backgrounds.
|
117 | *
|
118 | * @default "bg-set"
|
119 | */
|
120 | data_bg_set?: string;
|
121 |
|
122 | /**
|
123 | * The name of the data attribute containing the value of poster to load lazily,
|
124 | * excluding the `"data-"` part.
|
125 | * E.g. if your data attribute is named `"data-poster"`, just pass `"poster"`.
|
126 | *
|
127 | * @default "poster"
|
128 | */
|
129 | data_poster?: string;
|
130 |
|
131 | /**
|
132 | * The class applied to the multiple background elements after the multiple
|
133 | * background was applied
|
134 | *
|
135 | * @default "applied"
|
136 | */
|
137 | class_applied?: string;
|
138 |
|
139 | /**
|
140 | * The class applied to the elements while the loading is in progress.
|
141 | *
|
142 | * @default "loading"
|
143 | */
|
144 | class_loading?: string;
|
145 |
|
146 | /**
|
147 | * The class applied to the elements when the loading is complete.
|
148 | *
|
149 | * @default "loaded"
|
150 | */
|
151 | class_loaded?: string;
|
152 |
|
153 | /**
|
154 | * The class applied to the elements when the element causes an error.
|
155 | *
|
156 | * @default "error"
|
157 | */
|
158 | class_error?: string;
|
159 |
|
160 | /**
|
161 | * The class applied to the elements after they entered the viewport.
|
162 | *
|
163 | * @default "entered"
|
164 | */
|
165 | class_entered?: string;
|
166 |
|
167 | /**
|
168 | * The class applied to the elements after they exited the viewport.
|
169 | *
|
170 | * @default "exited"
|
171 | */
|
172 | class_exited?: string;
|
173 |
|
174 | /**
|
175 | * A boolean that defines whether or not to automatically unobserve
|
176 | * elements once they've loaded or throwed an error
|
177 | *
|
178 | * @default true
|
179 | */
|
180 | unobserve_completed?: boolean;
|
181 |
|
182 | /**
|
183 | * A boolean that defines whether or not to automatically unobserve
|
184 | * elements once they entered the viewport
|
185 | *
|
186 | * @default false
|
187 | */
|
188 | unobserve_entered?: boolean;
|
189 |
|
190 | /**
|
191 | * A boolean that defines whether or not to cancel the download of the
|
192 | * images that exit the viewport while they are still loading, eventually
|
193 | * restoring the original attributes. It applies only to images so to the
|
194 | * `img` (and `picture`) tags, so it doesn't apply to background images,
|
195 | * `iframe`s nor `video`s.
|
196 | *
|
197 | * @default true
|
198 | */
|
199 | cancel_on_exit?: boolean;
|
200 |
|
201 | /**
|
202 | * A callback function which is called whenever an element enters the viewport.
|
203 | * Arguments: DOM element, intersection observer entry, lazyload instance.
|
204 | */
|
205 | callback_enter?: (
|
206 | elt: HTMLElement,
|
207 | entry: IntersectionObserverEntry,
|
208 | instance: ILazyLoadInstance
|
209 | ) => void;
|
210 |
|
211 | /**
|
212 | * A callback function which is called whenever an element exits the viewport.
|
213 | * Arguments: `DOM element`, `intersection observer entry`, `lazyload instance`.
|
214 | */
|
215 | callback_exit?: (
|
216 | elt: HTMLElement,
|
217 | entry: IntersectionObserverEntry,
|
218 | instance: ILazyLoadInstance
|
219 | ) => void;
|
220 |
|
221 | /**
|
222 | * A callback function which is called whenever a multiple background
|
223 | * element starts loading.
|
224 | * Arguments: `DOM element`, `lazyload instance`.
|
225 | */
|
226 | callback_applied?: (elt: HTMLElement, instance: ILazyLoadInstance) => void;
|
227 |
|
228 | /**
|
229 | * A callback function which is called whenever an element starts loading.
|
230 | * Arguments: `DOM element`, `lazyload instance`.
|
231 | */
|
232 | callback_loading?: (elt: HTMLElement, instance: ILazyLoadInstance) => void;
|
233 |
|
234 | /**
|
235 | * A callback function which is called whenever an element finishes loading.
|
236 | * Note that, in version older than 11.0.0, this option went under the
|
237 | * name `callback_load`.
|
238 | * Arguments: `DOM element`, `lazyload instance`.
|
239 | */
|
240 | callback_loaded?: (elt: HTMLElement, instance: ILazyLoadInstance) => void;
|
241 |
|
242 | /**
|
243 | * A callback function which is called whenever an element triggers an error.
|
244 | * Arguments: `DOM element`, `lazyload instance`.
|
245 | */
|
246 | callback_error?: (elt: HTMLElement, instance: ILazyLoadInstance) => void;
|
247 |
|
248 | /**
|
249 | * A callback function which is called when there are no more elements to load and all elements have been downloaded.
|
250 | * Arguments: `lazyload instance`.
|
251 | */
|
252 | callback_finish?: (instance: ILazyLoadInstance) => void;
|
253 |
|
254 | /**
|
255 | * A callback function which is called whenever an element loading is
|
256 | * canceled while loading, as for `cancel_on_exit: true`
|
257 | */
|
258 | callback_cancel?: (
|
259 | elt: HTMLElement,
|
260 | entry: IntersectionObserverEntry,
|
261 | instance: ILazyLoadInstance
|
262 | ) => void;
|
263 |
|
264 | /**
|
265 | * This boolean sets whether or not to use [native lazy loading](https://addyosmani.com/blog/lazy-loading/)
|
266 | * to do [hybrid lazy loading](https://www.smashingmagazine.com/2019/05/hybrid-lazy-loading-progressive-migration-native/).
|
267 | * On browsers that support it, LazyLoad will set the `loading="lazy"` attribute on `images` and `iframes`,
|
268 | * and delegate their loading to the browser.
|
269 | *
|
270 | * @default false
|
271 | */
|
272 | use_native?: boolean;
|
273 |
|
274 | /**
|
275 | * Tells LazyLoad if to restore the original values of `src`, `srcset` and `sizes`
|
276 | * when a loading error occurs.
|
277 | *
|
278 | * @default false
|
279 | */
|
280 | restore_on_error?: boolean;
|
281 | }
|
282 |
|
283 | export interface ILazyLoadInstance {
|
284 | /**
|
285 | * Make LazyLoad to re-check the DOM for `elements_selector` elements inside its `container`.
|
286 | *
|
287 | * ### Use case
|
288 | *
|
289 | * Update LazyLoad after you added or removed DOM elements to the page.
|
290 | */
|
291 | update: (elements?: NodeListOf<HTMLElement>) => void;
|
292 |
|
293 | /**
|
294 | * Destroys the instance, unsetting instance variables and removing listeners.
|
295 | *
|
296 | * ### Use case
|
297 | *
|
298 | * Free up some memory. Especially useful for Single Page Applications.
|
299 | */
|
300 | destroy: () => void;
|
301 |
|
302 | /**
|
303 | * Loads all the lazy elements right away and stop observing them,
|
304 | * no matter if they are inside or outside the viewport,
|
305 | * no matter if they are hidden or visible.
|
306 | *
|
307 | * ### Use case
|
308 | *
|
309 | * To load all the remaining elements in advance
|
310 | */
|
311 | loadAll: () => void;
|
312 |
|
313 | /**
|
314 | * Restores DOM to its original state. Note that it doesn't destroy LazyLoad,
|
315 | * so you probably want to use it along with destroy().
|
316 | *
|
317 | * ### Use case
|
318 | *
|
319 | * Reset the DOM before a soft page navigation (SPA) occures, e.g. using TurboLinks.
|
320 | */
|
321 | restoreAll: () => void;
|
322 |
|
323 | /**
|
324 | * The number of elements that are currently downloading from the network
|
325 | * (limitedly to the ones managed by the instance of LazyLoad).
|
326 | * This is particularly useful to understand whether
|
327 | * or not is safe to destroy this instance of LazyLoad.
|
328 | */
|
329 | loadingCount: number;
|
330 |
|
331 | /**
|
332 | * The number of elements that haven't been lazyloaded yet
|
333 | * (limitedly to the ones managed by the instance of LazyLoad)
|
334 | */
|
335 | toLoadCount: number;
|
336 | }
|
337 |
|
338 | export interface ILazyLoad {
|
339 | new (options?: ILazyLoadOptions, elements?: NodeListOf<HTMLElement>): ILazyLoadInstance;
|
340 |
|
341 | /**
|
342 | * Immediately loads the lazy `element`.
|
343 | * You can pass your custom options in the settings parameter.
|
344 | * Note that the `elements_selector` option has no effect,
|
345 | * since you are passing the element as a parameter.
|
346 | * Also note that this method has effect only once on a specific `element`.
|
347 | *
|
348 | * ### Use case
|
349 | *
|
350 | * To load an `element` at mouseover or at any other event different than "entering the viewport"
|
351 | */
|
352 | load(element: HTMLElement, settings: ILazyLoadOptions): void;
|
353 |
|
354 | /**
|
355 | * Resets the internal status of the given element.
|
356 | *
|
357 | * ### Use case
|
358 | *
|
359 | * To tell LazyLoad to consider this `element` again, for example if you changed
|
360 | * the `data-src` attribute after the previous `data-src` was loaded,
|
361 | * call this method, then call `update()`.
|
362 | */
|
363 | resetStatus(element: HTMLElement): void;
|
364 | }
|
365 |
|
366 | declare var LazyLoad: ILazyLoad;
|
367 | export default LazyLoad;
|