0
# Plugin Installation
1

2
Vue Lazyload plugin installation and configuration system for registering directives, components, and providing global access to the lazy loading handler.
3

4
## Capabilities
5

6
### Plugin Installation
7

8
Installs Vue Lazyload plugin into a Vue 3 application with optional configuration.
9

10
```typescript { .api }
11
/**
12
 * Vue Lazyload plugin object with install method
13
 */
14
interface VueLazyloadPluginObject {
15
  /**
16
   * Installs the plugin into Vue application
17
   * @param Vue - Vue 3 App instance
18
   * @param options - Optional configuration options
19
   */
20
  install(Vue: App, options?: VueLazyloadOptions): void;
21
}
22

23
/**
24
 * Configuration options for Vue Lazyload plugin
25
 */
26
interface VueLazyloadOptions {
27
  /** Enable lazy-component registration (default: false) */
28
  lazyComponent?: boolean;
29
  /** Enable lazy-image component registration (default: false) */
30
  lazyImage?: boolean;
31
  /** Proportion of pre-loading height (default: 1.3) */
32
  preLoad?: number;
33
  /** Error image URL fallback */
34
  error?: string;
35
  /** Loading placeholder image URL */
36
  loading?: string;
37
  /** CORS setting for image loading */
38
  cors?: string;
39
  /** Maximum loading attempt count (default: 3) */
40
  attempt?: number;
41
  /** DOM events to listen for scroll detection */
42
  listenEvents?: string[];
43
  /** WebP format support detection */
44
  supportWebp?: boolean;
45
  /** Element adapter callbacks for lifecycle events */
46
  adapter?: AdapterOptions;
47
  /** Image listener filters for URL modification */
48
  filter?: FilterOptions;
49
  /** Dispatch DOM events on state changes (default: false) */
50
  dispatchEvent?: boolean;
51
  /** Throttle delay for scroll events in ms (default: 200) */
52
  throttleWait?: number;
53
  /** Use IntersectionObserver instead of scroll events (default: false) */
54
  observer?: boolean;
55
  /** IntersectionObserver configuration options */
56
  observerOptions?: IntersectionObserverInit;
57
  /** Suppress debug console output (default: true) */
58
  silent?: boolean;
59
  /** Top offset for pre-loading (default: 0) */
60
  preLoadTop?: number;
61
  /** Device pixel ratio scale factor */
62
  scale?: number;
63
}
64

65
/**
66
 * Element adapter callbacks for handling lifecycle events
67
 */
68
interface AdapterOptions {
69
  /** Called when image loading starts */
70
  loading?: (listener: VueReactiveListener, options: VueLazyloadOptions) => void;
71
  /** Called when image successfully loads */
72
  loaded?: (listener: VueReactiveListener, options: VueLazyloadOptions) => void;
73
  /** Called when image loading fails */
74
  error?: (listener: VueReactiveListener, options: VueLazyloadOptions) => void;
75
  /** Called before image loading starts */
76
  beforeLoad?: (listener: VueReactiveListener, options: VueLazyloadOptions) => void;
77
}
78

79
/**
80
 * Image listener filters for modifying image URLs
81
 */
82
interface FilterOptions {
83
  [filterName: string]: (listener: VueReactiveListener, options: VueLazyloadOptions) => void;
84
}
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
import { createApp } from "vue";
91
import VueLazyload from "vue-lazyload";
92
import App from "./App.vue";
93

94
const app = createApp(App);
95

96
// Basic installation
97
app.use(VueLazyload);
98

99
// Installation with configuration
100
app.use(VueLazyload, {
101
  preLoad: 1.3,
102
  error: "/images/error.png",
103
  loading: "/images/loading.gif",
104
  attempt: 3,
105
  observer: true,
106
  observerOptions: {
107
    rootMargin: "0px",
108
    threshold: 0.1,
109
  },
110
  lazyComponent: true,
111
  lazyImage: true,
112
});
113

114
// Advanced configuration with adapters and filters
115
app.use(VueLazyload, {
116
  adapter: {
117
    loaded({ el, naturalHeight, naturalWidth, src }) {
118
      console.log("Image loaded:", src, { naturalHeight, naturalWidth });
119
      el.style.opacity = "1";
120
    },
121
    loading(listener) {
122
      console.log("Loading image:", listener.src);
123
    },
124
    error(listener) {
125
      console.error("Failed to load image:", listener.src);
126
    },
127
  },
128
  filter: {
129
    progressive(listener, options) {
130
      const isCDN = /cdn\.example\.com/.test(listener.src);
131
      if (isCDN) {
132
        listener.loading = listener.src + "?w=10&h=10";
133
      }
134
    },
135
    webp(listener, options) {
136
      if (options.supportWebp) {
137
        const isCDN = /cdn\.example\.com/.test(listener.src);
138
        if (isCDN) {
139
          listener.src += "?format=webp";
140
        }
141
      }
142
    },
143
  },
144
});
145

146
app.mount("#app");
147
```
148

149
### Global Properties
150

151
After installation, Vue Lazyload adds global properties to Vue instances.
152

153
```typescript { .api }
154
/**
155
 * Global properties added to Vue component instances
156
 */
157
interface ComponentPublicInstance {
158
  /** Access to the lazy loading handler instance */
159
  $Lazyload: VueLazyloadHandler;
160
}
161

162
/**
163
 * Global properties added to Vue app config
164
 */
165
interface AppConfig {
166
  globalProperties: {
167
    /** Global access to lazy loading handler */
168
    $Lazyload: VueLazyloadHandler;
169
  };
170
}
171
```
172

173
**Usage Examples:**
174

175
```vue
176
<script setup>
177
import { getCurrentInstance } from "vue";
178

179
// Access via composition API
180
const instance = getCurrentInstance();
181
const lazyload = instance?.appContext.config.globalProperties.$Lazyload;
182

183
// Listen for events
184
lazyload?.$on("loaded", (listener, cache) => {
185
  console.log("Image loaded:", listener.src, "from cache:", cache);
186
});
187

188
// Manually trigger lazy load check
189
lazyload?.lazyLoadHandler();
190

191
// Get performance metrics
192
const metrics = lazyload?.performance();
193
console.log("Performance data:", metrics);
194
</script>
195
```
196

197
```vue
198
<script>
199
export default {
200
  mounted() {
201
    // Access via options API
202
    this.$Lazyload.$on("error", (listener) => {
203
      console.error("Failed to load:", listener.src);
204
    });
205
  },
206
};
207
</script>
208
```
209

210
### Provide/Inject System
211

212
Vue Lazyload also provides the handler via Vue's provide/inject system.
213

214
```typescript { .api }
215
/**
216
 * Injection key for accessing lazy loading handler
217
 */
218
const LazyloadInjectionKey: InjectionKey<VueLazyloadHandler>;
219
```
220

221
**Usage Example:**
222

223
```vue
224
<script setup>
225
import { inject } from "vue";
226

227
// Inject the lazyload handler
228
const lazyload = inject("Lazyload");
229

230
// Use the injected handler
231
lazyload?.$on("loaded", (listener) => {
232
  console.log("Loaded:", listener.src);
233
});
234
</script>
235
```