0
# Vue Lazyload
1

2
Vue Lazyload is a Vue.js plugin designed for lazy-loading images and components in Vue 3 applications. It provides directives (v-lazy, v-lazy-container), components (lazy-component, lazy-image), and programmatic APIs for optimizing image loading performance.
3

4
## Package Information
5

6
- **Package Name**: vue-lazyload
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vue-lazyload`
10

11
## Core Imports
12

13
```typescript
14
import VueLazyload from "vue-lazyload";
15

16
// Named exports for TypeScript support
17
import { 
18
  VueLazyloadOptions, 
19
  VueLazyloadHandler, 
20
  VueReactiveListener, 
21
  loadImageAsyncOption 
22
} from "vue-lazyload";
23
```
24

25
For CommonJS:
26

27
```javascript
28
const VueLazyload = require("vue-lazyload");
29
const { VueLazyloadOptions, VueLazyloadHandler } = require("vue-lazyload");
30
```
31

32
## Basic Usage
33

34
```typescript
35
import { createApp } from "vue";
36
import VueLazyload from "vue-lazyload";
37
import App from "./App.vue";
38

39
const app = createApp(App);
40

41
// Install with default options
42
app.use(VueLazyload);
43

44
// Or install with custom options
45
app.use(VueLazyload, {
46
  preLoad: 1.3,
47
  error: "/error.png",
48
  loading: "/loading.gif",
49
  attempt: 3,
50
  observer: true,
51
  lazyComponent: true,
52
  lazyImage: true
53
});
54

55
app.mount("#app");
56
```
57

58
In templates:
59

60
```vue
61
<template>
62
  <div>
63
    <!-- Basic lazy loading -->
64
    <img v-lazy="imageUrl" alt="Lazy loaded image">
65
    
66
    <!-- Background image lazy loading -->
67
    <div v-lazy:background-image="backgroundUrl"></div>
68
    
69
    <!-- Container-based lazy loading -->
70
    <div v-lazy-container="{ selector: 'img' }">
71
      <img data-src="/image1.jpg">
72
      <img data-src="/image2.jpg">
73
    </div>
74
    
75
    <!-- Lazy component -->
76
    <lazy-component @show="onComponentShow">
77
      <img :src="heavyImageUrl" alt="Heavy image">
78
    </lazy-component>
79
  </div>
80
</template>
81
```
82

83
## Architecture
84

85
Vue Lazyload is built around several key components:
86

87
- **Plugin System**: Vue plugin that registers directives, components, and provides global access
88
- **Lazy Handler**: Core lazy loading logic with IntersectionObserver or event-based detection
89
- **Reactive Listeners**: Individual image listeners that manage loading states and rendering
90
- **Container Manager**: Handles lazy loading for multiple images within containers
91
- **Components**: Vue components for lazy loading content and images
92
- **Event System**: Hooks for loading, loaded, and error events
93

94
## Capabilities
95

96
### Plugin Installation
97

98
Main plugin installation and configuration system for registering directives and components.
99

100
```typescript { .api }
101
interface VueLazyloadPluginObject {
102
  install(Vue: App, options?: VueLazyloadOptions): void;
103
}
104

105
interface VueLazyloadOptions {
106
  lazyComponent?: boolean;
107
  lazyImage?: boolean;
108
  preLoad?: number;
109
  error?: string;
110
  loading?: string;
111
  cors?: string;
112
  attempt?: number;
113
  listenEvents?: string[];
114
  supportWebp?: boolean;
115
  adapter?: AdapterOptions;
116
  filter?: FilterOptions;
117
  dispatchEvent?: boolean;
118
  throttleWait?: number;
119
  observer?: boolean;
120
  observerOptions?: IntersectionObserverInit;
121
  silent?: boolean;
122
  preLoadTop?: number;
123
  scale?: number;
124
}
125
```
126

127
[Plugin Installation](./plugin-installation.md)
128

129
### Directive Usage
130

131
Vue directives for declarative lazy loading of images and background images.
132

133
```typescript { .api }
134
// v-lazy directive
135
interface LazyDirective {
136
  beforeMount(el: HTMLElement, binding: DirectiveBinding, vnode: VNode): void;
137
  beforeUpdate(el: HTMLElement, binding: DirectiveBinding, vnode: VNode): void;
138
  updated(el: HTMLElement, binding: DirectiveBinding, vnode: VNode): void;
139
  unmounted(el: HTMLElement, binding: DirectiveBinding, vnode: VNode): void;
140
}
141

142
// v-lazy-container directive
143
interface LazyContainerDirective {
144
  beforeMount(el: HTMLElement, binding: DirectiveBinding, vnode: VNode): void;
145
  updated(el: HTMLElement, binding: DirectiveBinding, vnode: VNode): void;
146
  unmounted(el: HTMLElement, binding: DirectiveBinding, vnode: VNode): void;
147
}
148
```
149

150
[Directive Usage](./directives.md)
151

152
### Lazy Components
153

154
Vue components for lazy loading content and images with full Vue 3 composition API support.
155

156
```typescript { .api }
157
interface LazyComponentProps {
158
  tag?: string;
159
}
160

161
interface LazyImageProps {
162
  src: string | VueLazyloadImageOptions;
163
  tag?: string;
164
}
165

166
interface VueLazyloadImageOptions {
167
  src: string;
168
  error?: string;
169
  loading?: string;
170
  attempt?: number;
171
}
172
```
173

174
[Lazy Components](./components.md)
175

176
### Programmatic API
177

178
Direct access to the lazy loading handler for manual control and event handling.
179

180
```typescript { .api }
181
interface VueLazyloadHandler {
182
  $on(event: string, callback: VueLazyloadListenEvent): void;
183
  $once(event: string, callback: VueLazyloadListenEvent): void;
184
  $off(event: string, callback?: VueLazyloadListenEvent): void;
185
  lazyLoadHandler(): void;
186
  performance(): VueReactiveListener[];
187
  add(el: HTMLElement, binding: DirectiveBinding, vnode: VNode): void;
188
  update(el: HTMLElement, binding: DirectiveBinding, vnode?: VNode): void;
189
  remove(el: HTMLElement): void;
190
  setMode(mode: string): void;
191
}
192
```
193

194
[Programmatic API](./programmatic-api.md)
195

196
## Types
197

198
```typescript { .api }
199
interface VueReactiveListener {
200
  el: Element;
201
  src: string;
202
  error: string;
203
  loading: string;
204
  bindType: string;
205
  attempt: number;
206
  naturalHeight: number;
207
  naturalWidth: number;
208
  options: VueLazyloadOptions;
209
  rect: DOMRect;
210
  $parent: Element;
211
  elRenderer: Function;
212
  performanceData: Performance;
213
}
214

215
interface VueLazyloadListenEvent {
216
  (listener: VueReactiveListener, cache: boolean): void;
217
}
218

219
interface Performance {
220
  init: number;
221
  loadStart: number;
222
  loadEnd: number;
223
}
224

225
interface AdapterOptions {
226
  [key: string]: (listener: VueReactiveListener, options: VueLazyloadOptions) => void;
227
}
228

229
interface FilterOptions {
230
  [key: string]: (listener: VueReactiveListener, options: VueLazyloadOptions) => void;
231
}
232

233
interface loadImageAsyncOption {
234
  src: string;
235
  cors?: string;
236
}
237
```