web-assets/lazyload/v17/typings/lazyload.d.ts

export interface ILazyLoadOptions {
  /**
     * The CSS selector of the elements to load lazily, which will be selected
     * as descendants of the `container` object.

     * @default ".lazy"
     */
  elements_selector?: string;

  /**
   * The scrolling container of the elements in the `elements_selector` option.
   *
   * @default document
   */
  container?: HTMLElement;

  /**
   * A number of pixels representing the outer distance off the scrolling area
   * from which to start loading the elements.
   * @default 300
   */
  threshold?: number;

  /**
   * Similar to `threshold`, but accepting multiple values and both `px` and `%`
   * units. It maps directly to the `rootMargin` property of IntersectionObserver,
   * so it must be a string with a syntax similar to the CSS `margin` property.
   * You can use it when you need to have different thresholds for the scrolling
   * area. It overrides `threshold` when passed.
   *
   * @default null
   *
   * @see https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin
   */
  thresholds?: string;

  /**
   * The name of the data attribute containing the element URL to load,
   * excluding the `"data-"` part.
   * E.g. if your data attribute is named `"data-src"`,
   * just pass `"src"`
   *
   * @default "src"
   */
  data_src?: string;

  /**
   * The name of the data attribute containing the image URL set to load,
   * in either img and source tags, excluding the "data-" part.
   * E.g. if your data attribute is named `"data-srcset"`,
   * just pass `"srcset"`
   *
   * @default "srcset"
   */
  data_srcset?: string;

  /**
   * The name of the data attribute containing the sizes attribute to use,
   * excluding the `"data-"` part.
   * E.g. if your data attribute is named `"data-sizes"`, just pass `"sizes"`
   *
   * @default "sizes"
   */
  data_sizes?: string;

  /**
   * The name of the data attribute containing the URL of `background-image`
   * to load lazily, excluding the `"data-"` part.
   * E.g. if your data attribute is named `"data-bg"`, just pass `"bg"`.
   * The attribute value must be a valid value for `background-image`,
   * including the `url()` part of the CSS instruction.
   *
   * @default "bg"
   */
  data_bg?: string;

  /**
   * The name of the data attribute containing the URL of `background-image`
   * to load lazily on HiDPI screens, excluding the `"data-"` part.
   * E.g. if your data attribute is named `"data-bg-hidpi"`, just pass `"bg-hidpi"`.
   * The attribute value must be a valid value for `background-image`,
   * including the `url()` part of the CSS instruction.
   *
   * @default "bg-hidpi"
   */
  data_bg_hidpi?: string;

  /**
   * The name of the data attribute containing the value of multiple `background-image`
   * to load lazily, excluding the `"data-"` part.
   * E.g. if your data attribute is named `"data-bg-multi"`, just pass `"bg-multi"`.
   * The attribute value must be a valid value for `background-image`,
   * including the `url()` part of the CSS instruction.
   *
   * @default "bg-multi"
   */
  data_bg_multi?: string;

  /**
   * The name of the data attribute containing the value of multiple `background-image`
   * to load lazily on HiDPI screens, excluding the `"data-"` part.
   * E.g. if your data attribute is named `"data-bg-multi-hidpi"`, just pass `"bg-multi-hidpi"`.
   * The attribute value must be a valid value for `background-image`,
   * including the `url()` part of the CSS instruction.
   *
   * @default "bg-multi-hidpi"
   */
  data_bg_multi_hidpi?: string;

  /**
   * The name of the data attribute containing the value of the background to
   * be applied with image-set, excluding the `"data-"` part.
   * E.g. if your data attribute is named `"data-bg-set"`, just pass `"bg-set"`.
   * The attribute value must be what goes inside the `image-set` CSS function.
   * You can separate values with a pipe (`|`) character to have
   * multiple backgrounds.
   *
   * @default "bg-set"
   */
  data_bg_set?: string;

  /**
   * The name of the data attribute containing the value of poster to load lazily,
   * excluding the `"data-"` part.
   * E.g. if your data attribute is named `"data-poster"`, just pass `"poster"`.
   *
   * @default "poster"
   */
  data_poster?: string;

  /**
   * The class applied to the multiple background elements after the multiple
   * background was applied
   *
   * @default "applied"
   */
  class_applied?: string;

  /**
   * The class applied to the elements while the loading is in progress.
   *
   * @default "loading"
   */
  class_loading?: string;

  /**
   * The class applied to the elements when the loading is complete.
   *
   * @default "loaded"
   */
  class_loaded?: string;

  /**
   * The class applied to the elements when the element causes an error.
   *
   * @default "error"
   */
  class_error?: string;

  /**
   * The class applied to the elements after they entered the viewport.
   *
   * @default "entered"
   */
  class_entered?: string;

  /**
   * The class applied to the elements after they exited the viewport.
   *
   * @default "exited"
   */
  class_exited?: string;

  /**
   * A boolean that defines whether or not to automatically unobserve
   * elements once they've loaded or throwed an error
   *
   * @default true
   */
  unobserve_completed?: boolean;

  /**
   * A boolean that defines whether or not to automatically unobserve
   * elements once they entered the viewport
   *
   * @default false
   */
  unobserve_entered?: boolean;

  /**
   * A boolean that defines whether or not to cancel the download of the
   * images that exit the viewport while they are still loading, eventually
   * restoring the original attributes. It applies only to images so to the
   * `img` (and `picture`) tags, so it doesn't apply to background images,
   * `iframe`s nor `video`s.
   *
   * @default true
   */
  cancel_on_exit?: boolean;

  /**
   * A callback function which is called whenever an element enters the viewport.
   * Arguments: DOM element, intersection observer entry, lazyload instance.
   */
  callback_enter?: (
    elt: HTMLElement,
    entry: IntersectionObserverEntry,
    instance: ILazyLoadInstance
  ) => void;

  /**
   * A callback function which is called whenever an element exits the viewport.
   * Arguments: `DOM element`, `intersection observer entry`, `lazyload instance`.
   */
  callback_exit?: (
    elt: HTMLElement,
    entry: IntersectionObserverEntry,
    instance: ILazyLoadInstance
  ) => void;

  /**
   * A callback function which is called whenever a multiple background
   * element starts loading.
   * Arguments: `DOM element`, `lazyload instance`.
   */
  callback_applied?: (elt: HTMLElement, instance: ILazyLoadInstance) => void;

  /**
   * A callback function which is called whenever an element starts loading.
   * Arguments: `DOM element`, `lazyload instance`.
   */
  callback_loading?: (elt: HTMLElement, instance: ILazyLoadInstance) => void;

  /**
   * A callback function which is called whenever an element finishes loading.
   * Note that, in version older than 11.0.0, this option went under the
   * name `callback_load`.
   * Arguments: `DOM element`, `lazyload instance`.
   */
  callback_loaded?: (elt: HTMLElement, instance: ILazyLoadInstance) => void;

  /**
   * A callback function which is called whenever an element triggers an error.
   * Arguments: `DOM element`, `lazyload instance`.
   */
  callback_error?: (elt: HTMLElement, instance: ILazyLoadInstance) => void;

  /**
   * A callback function which is called when there are no more elements to load and all elements have been downloaded.
   * Arguments: `lazyload instance`.
   */
  callback_finish?: (instance: ILazyLoadInstance) => void;

  /**
   * A callback function which is called whenever an element loading is
   * canceled while loading, as for `cancel_on_exit: true`
   */
  callback_cancel?: (
    elt: HTMLElement,
    entry: IntersectionObserverEntry,
    instance: ILazyLoadInstance
  ) => void;

  /**
   * This boolean sets whether or not to use [native lazy loading](https://addyosmani.com/blog/lazy-loading/)
   * to do [hybrid lazy loading](https://www.smashingmagazine.com/2019/05/hybrid-lazy-loading-progressive-migration-native/).
   * On browsers that support it, LazyLoad will set the `loading="lazy"` attribute on `images` and `iframes`,
   * and delegate their loading to the browser.
   *
   * @default false
   */
  use_native?: boolean;

  /**
   * Tells LazyLoad if to restore the original values of `src`, `srcset` and `sizes` 
   * when a loading error occurs.
   *
   * @default false
   */
  restore_on_error?: boolean;
}

export interface ILazyLoadInstance {
  /**
   * Make LazyLoad to re-check the DOM for `elements_selector` elements inside its `container`.
   *
   * ### Use case
   *
   * Update LazyLoad after you added or removed DOM elements to the page.
   */
  update: (elements?: NodeListOf<HTMLElement>) => void;

  /**
   * Destroys the instance, unsetting instance variables and removing listeners.
   *
   * ### Use case
   *
   * Free up some memory. Especially useful for Single Page Applications.
   */
  destroy: () => void;

  /**
   * Loads all the lazy elements right away and stop observing them,
   * no matter if they are inside or outside the viewport,
   * no matter if they are hidden or visible.
   *
   * ### Use case
   *
   * To load all the remaining elements in advance
   */
  loadAll: () => void;

  /**
   * Restores DOM to its original state. Note that it doesn't destroy LazyLoad,
   * so you probably want to use it along with destroy().
   *
   * ### Use case
   *
   * Reset the DOM before a soft page navigation (SPA) occures, e.g. using TurboLinks.
   */
  restoreAll: () => void;

  /**
   * The number of elements that are currently downloading from the network
   * (limitedly to the ones managed by the instance of LazyLoad).
   * This is particularly useful to understand whether
   * or not is safe to destroy this instance of LazyLoad.
   */
  loadingCount: number;

  /**
   * The number of elements that haven't been lazyloaded yet
   * (limitedly to the ones managed by the instance of LazyLoad)
   */
  toLoadCount: number;
}

export interface ILazyLoad {
  new (options?: ILazyLoadOptions, elements?: NodeListOf<HTMLElement>): ILazyLoadInstance;

  /**
   * Immediately loads the lazy `element`.
   * You can pass your custom options in the settings parameter.
   * Note that the `elements_selector` option has no effect,
   * since you are passing the element as a parameter.
   * Also note that this method has effect only once on a specific `element`.
   *
   * ### Use case
   *
   * To load an `element` at mouseover or at any other event different than "entering the viewport"
   */
  load(element: HTMLElement, settings: ILazyLoadOptions): void;

  /**
   * Resets the internal status of the given element.
   *
   * ### Use case
   *
   * To tell LazyLoad to consider this `element` again, for example if you changed
   * the `data-src` attribute after the previous `data-src` was loaded,
   * call this method, then call `update()`.
   */
  resetStatus(element: HTMLElement): void;
}

declare var LazyLoad: ILazyLoad;
export default LazyLoad;