vue-l-lazyload

A lazyload and in-view detection plugin for Vue.js v2.x+.

Demo

Live demo or npm install vue-l-lazyload && npm run startDev to play it!

Pull requests are welcome :)

License

LGPL-V3

Features

No extra dependencies except Vue
Progressive configuration
Flexible events to trigger loading
Lazyload as src attribute and background image are supported
Customized retry control
Filters for substitution of url by rules
Performance boost by event delegation and passive event listener when it's available
LazyComp for lazy loading child component.
InViewComp for in-view detection

Installation

npm install vue-l-lazyload

Usage

A simple way:

import { VueLLazyload } from 'vue-l-lazyload';
// For smaller production code with tree shaking, I recommend you to import the src instead:
// import { VueLLazyloadLocal: VueLLazyload } from 'vue-l-lazyload/src';
Vue.use(VueLLazyload, {
    events: 'scroll'
});
// The root $lazy "Vue.$lazy" will be available after it's been installed

<img lazy="xxx.png">

A more configurable way:

import { VueLLazyload } from 'vue-l-lazyload';
Vue.use(VueLLazyload, config);

<lazy-ref ref="lazyRef" opts="config">
    <img lazy="{src:xxx.png, ref:'lazyRef'}">
</lazy-ref>

Vue Plugins

VueLLazyload

Vue Plugin with global option of registering directive "lazy" and component "lazy-ref".

VueLLazyloadLocal

Vue Plugin without global option of registering directives or components for local usage purpose and smaller footprint.

Config

Notes about Config

Note that ALL ANCESTORS' CONFIGS WILL BE INHERITED level by level. So be careful there may be conflict problems if you use too many ancestors' configs!

Available Config Table

Name	Type	Default	Description
events	String or Array<String>	scroll	Events to be bound with.
preloadRatio	Number	1	The "resize" ratio of parent view when it's children views compare with it.
onEnter	Function	-	It will be triggered if the element enters the sight. The argument will be a object: { // The LazyLoader $lazy, }
onLeave	Function	-	It will be triggered if the element leaves the sight. The argument will be a object: { // The LazyLoader $lazy, }
throttleMethod	String	debounce	Throttling method. Available values: "debounce", "throttle"
throttleTime	Integer	250	Throttling time in ms.
regGlobal	Boolean	true	Whether to register the directive "lazy" and component "lazy-ref" globally or not. Only available for global config of "VueLLazyload".

[1]: All options will inherit its ancestors' options.

LazyLoader

$lazy is Instance of LazyLoader, available for LazyRef and InViewComp.

Methods

Name	Arguments	Description
check	-	Manually check and load itself and its children loaders which haven't loaded.

Directives

Lazy(v-lazy)

value

Type	Description
String or Object	If the value is an Object, it has the same spec as config with extra config. If the value is a String, it will be used as `src` of config

Extra config for the Value of Lazy

Name

Type

Default

Description

ref

String

`null`

The name of parent view (lazy-ref component or window).
If it's not specified, it will be the window.
By now, it only supports one level of LazyRef parent.

src^[2]

String

The resource url going to be loaded.
Only available for Lazy.

filters

Array<Function>

Filter the src you one by one before the element requests it.
Each filter is a function and should return the filtered url. The signiture of it should be like this:

function: String (
    // Last filtered result. It will be the original src if it's the first filter.
    lastResult,
    // Other infomation
    info: {
        // The element to which the loader attaches
        el,
    },
) {}

retry

Integer or Function

If it's a number, it will be the retry amount, 0 for no retry, -1 for infinite retry.
If it's a function, it will be used to control the flow of retry.
It will pass a object parameter which has following properties:

Name	Type	Description
el	HtmlElement	The element which the loader is bound to.
src	String	The last src which is loaded.
oSrc	String	The original src you want to load.
times	Integer	N-th times retry. Begins from 0.
next	Function	Call this function and pass an parameter object to it to control the retry. If you want to retry with the new url, you should pass it as `src` property. If you want to stop the retry, you should pass `true` as `failed` property.
applyFilters	Function	A shortcut function to apply all filters you passed as the option. Put the url into it and you will get the filtered one.

classLoading

String

lazy-loading

Class name of loading
Only available for Lazy.

classLoaded

String

lazy-loaded

Class name of loaded
Only available for Lazy.

classErr

String

lazy-err

Class name of load error
Only available for Lazy.

classTarget

String

self

Element (real node) of class name to be changed when the load stat changes.
If it's set to `parent`, the class name of parent element will be changed.
By default, the class name of element it self will be changed.

once

Boolean

true

Remove listener after it has loaded if it is set to true.

mode

String

The mode the lazyload.
If it's set to 'bg', the resource will be loaded as a background image.
By default, it will be set as the "src" attribute of the element.
Only available for Lazy and LazyRef.

onLoad

Function

It will be called when the src is loaded successfully (after retry if it did retry).
It will pass a object parameter which has following properties:

Name	Type	Description
el	HtmlElement	The element which the loader is bound to.
src	String	The last src which is loaded.
oSrc	String	The original src you want to load.

onErr

Function

It will be called when the src fails to load each time.
It will pass a object parameter which has following properties:

Name	Type	Description
el	HtmlElement	The element which the loader is bound to.
src	String	The last src which is loaded.
oSrc	String	The original src you want to load.
isEnd	Boolean	Optional. It will be true when it's the failure of the last loading (after all retries if it did retry).

onReq

Function

It will be called when the load request begins to be sent each time.
It will pass a object parameter which has following properties:

Name	Type	Description
el	HtmlElement	The element which the loader is bound to.
src	String	The last src which is loaded.
oSrc	String	The original src you want to load.

[1]: All options should not be changed after they have initialized except for [2].
[2]: It will mark the node not loaded and load again when it's in parent view. if once is set to false.
[3]: All options will inherit its ancestors' options.

Components

LazyRef(lazy-ref, Experimental)

Name	Type	Default	Description
tag	String	div	The tag name of the wrapper component when it renders.
opts	Object	null	See config. And it can be used a parent option to be inherited.

InViewComp

Extra config for `opts` InViewComp

Name

Type

Default

Description

onInView

Function

It will be called when the element is in the viewport.
It will pass wa object parameter which has following properties:

Name	Type	Description
$lazy	LazyLoader	The LazyLoader.
endCheck	Function	Call this function to stop checking whether the element is in viewport when you don't need onInView callback's firing anymore. This function will also be called if the stat is set to `COMP_LOADED`.

[1]: All options above won't inherit its ancestors' options by now.

LazyComp

Props

Name

Type

Default Value

Description

tag

String

div

The tag name of the wrapper component when it renders.

opts

Object

null

It has the same spec as config with extra config.

stat

Integer

COMP_NOT_LOAD

The status of the component which controls the slot's display.
Available constants for stat:

Name	Description
COMP_NOT_LOAD	The component is not loaded and the initial status of comopnent.
COMP_LOADING	The component is not loading.
COMP_LOADED	The component is not loaded.
COMP_ERR	The component failed to load.

Notes:

Please USE THE CONSTANT VARIABLE instead of the actual value!
The initial stat MUST be `COMP_NOT_LOAD` and the stat SHOULD NOT be changed until this component is mounted for LazyLoader's initialization.
To ensure you change the status after the initialization, you should change the props "stat" in the "onInView" callback.

Extra config for `opts` LazyComp

Name

Type

Default

Description

classCompLoading

String

comp-stat-loading

Class name of loading
Only available for LazyComp.

classCompLoaded

String

comp-stat-loaded

Class name of loaded
Only available for LazyComp.

classCompErr

String

comp-stat-err

Class name of load error
Only available for LazyComp.

classCompNotLoad

String

comp-stat-err

Class name of load error
Only available for LazyComp.

onInView

Function

It will be called when the element is in the viewport.
It will pass wa object parameter which has following properties:

Name	Type	Description
$lazy	LazyLoader	The LazyLoader.
endCheck	Function	Call this function to stop checking whether the element is in viewport when you don't need onInView callback's firing anymore. This function will also be called if the stat is set to `COMP_LOADED`.

[1]: All options above won't inherit its ancestors' options by now.

Slots

Name	Description
not-load	It will be shown if the prop `stat` is set to `COMP_NOT_LOAD`.
loading	It will be shown if the prop `stat` is set to `COMP_LOADING`.
err	It will be shown if the prop `stat` is set to `COMP_ERR`.
(default)	It will be shown if the prop `stat` is set to `COMP_LOADED`.

Well, what's next?

More abilities
More test cases
Performance optimization

vue-l-lazyload

vue-l-lazyload

Demo

Pull requests are welcome :)

License

Features

Installation

Usage

A simple way:

A more configurable way:

Vue Plugins

VueLLazyload

VueLLazyloadLocal

Config

Notes about Config

Available Config Table

LazyLoader

Methods

Directives

Lazy(v-lazy)

value

Extra config for the Value of Lazy

Components

LazyRef(lazy-ref, Experimental)

InViewComp

Extra config for opts InViewComp

LazyComp

Props

Extra config for opts LazyComp

Slots

Well, what's next?

Extra config for `opts` InViewComp

Extra config for `opts` LazyComp