You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This component approach swaps slots based on the image's loading state. Thus allowing you to use anything as a preloader, such as [component frameworks](https://github.com/vuejs/awesome-vue#frameworks)' spinners and progress bars. Such method also enables transitioning between states, a designer's dream.
13
+
Swaps between your image and another component when loading images, allowing you to use loaders from [component frameworks](https://github.com/vuejs/awesome-vue#frameworks) such as spinners and progress bars. This method also allows transitioning between the two components.
14
14
15
15
## Demo
16
16
17
17
Check out the [example page](https://matheusgrieger.github.io/vue-clazy-load/example/index.html).
18
18
19
19
## Installation
20
20
21
-
Select one:
21
+
Install with npm or yarn:
22
22
23
-
1. Install using **npm**
24
-
25
-
```sh
26
-
npm install vue-clazy-load --save
27
-
```
28
-
You can omit the `--save` option if using `npm@^5`.
29
-
30
-
You can also use Yarn (recommended) as:
31
-
32
-
```sh
33
-
yarn add vue-clazy-load
34
-
```
23
+
```sh
24
+
npm install vue-clazy-load
25
+
yarn add vue-clazy-load
26
+
```
35
27
36
-
Then in your JavaScript file:
28
+
Then simply import it to your project through the method that suits you best
37
29
30
+
* ES6+
38
31
```js
39
-
importVueClazyLoadfrom'vue-clazy-load'// ES6 (Babel and others)
Using Clazy Load is easy. The HTML code you need is the following:
66
+
Clazy Load works without any JS configuration as is, all you need is the basic HTML markup:
71
67
72
68
```html
73
69
<clazy-loadsrc="https://unsplash.it/500">
@@ -77,68 +73,110 @@ Using Clazy Load is easy. The HTML code you need is the following:
77
73
</div>
78
74
</clazy-load>
79
75
```
80
-
81
-
And no JS code is needed whatsoever, Clazy Load works out of the box.
76
+
The only required prop you must set is `src` that must correspond to your image's.
82
77
83
78
### Props
84
79
85
-
The component needs some configuration, though. There's only one required option, keeping it pretty simple.
80
+
All props supported by Clazy Load are listed below with their types and explanation.
81
+
82
+
#### `src`
83
+
84
+
* Type: string
85
+
* Default: none
86
+
*_Required_
87
+
88
+
Source of the image to be loaded. Must match your `<img>` tag src.
89
+
90
+
#### `tag`
91
+
92
+
* Type: string
93
+
* Default: `"div"`
94
+
95
+
What tag the component should render to.
96
+
97
+
#### `element`
98
+
99
+
* Type: string
100
+
* Default: `null`
86
101
87
-
| Prop | Description | Type | Default |
88
-
|------|-------------|------|---------|
89
-
| src | Image source that will be loaded. | String |_required_|
90
-
| tag | What tag the component will render to, like [vue-router router-link component](https://router.vuejs.org/en/api/router-link.html). | String | div |
91
-
| element | Selector for IntersectionObserver's root element. Leave blank to use _viewport_. See below for more details. | String |`null`|
92
-
| threshold | Values for IntersectionObserver's threshold option. See below for more details. | Array/Number |`[0, 0.5, 1]`|
93
-
| ratio | Element visibility percentage to compare and trigger loading. Must be between 0 and 1. | Number |`0.4`|
94
-
| margin | IntersectionObserver's margin option. See original documentation for more details. | String | '0px' |
102
+
Selector for Intersecion Observer's root element. Leave blank/null to use _viewport_.
95
103
96
-
###Classes
104
+
#### `threshold`
97
105
98
-
Custom classes on the Clazy Load component are passed to the rendered output.
106
+
* Type: Array | number
107
+
* Default: `[0, 0.5, 1]`
99
108
100
-
Also, the component adds `loading` and `loaded` classes to the **root** element regarding the two possible states, enabling further customization with CSS.
109
+
Values for Intersection Observer's threshold option.
110
+
111
+
#### `ratio`
112
+
113
+
* Type: number
114
+
* Default: `0.4`
115
+
116
+
Percent of the element that needs to be visible to trigger loading. Must be > 0 and <= 1.
117
+
118
+
#### `margin`
119
+
120
+
* Type: string
121
+
* Default: `"0px"`
122
+
123
+
Intersection Observer's margin option.
124
+
125
+
You can read more on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) about every Intersection Observer-specific prop and what they do.
Sets image's `crossOrigin` option and allows loading external images. Useful for Service Workers and caching.
134
+
135
+
#### `loadedClass`
136
+
137
+
* Type: string
138
+
* Default: `"loaded"`
139
+
140
+
#### `loadingClass`
141
+
142
+
* Type: string
143
+
* Default: `"loading"`
144
+
145
+
#### `errorClass`
146
+
147
+
* Type: string
148
+
* Default: `null`
149
+
150
+
All classes are added to the **root** element, not the image itself.
101
151
102
152
### Events
103
153
104
-
There is currently one event available for you to listen to on the component.
154
+
#### `loading`
105
155
106
-
| Event | Description |
107
-
|-------|-------------|
108
-
| load | Event emitted when image finishes loading |
109
-
| error | Event emitted if the image fails to load for whatever reason |
156
+
Image started loading and placeholder is visible.
110
157
111
-
###Sub-components and elements
158
+
#### `load`
112
159
113
-
The reason the component has a `src` prop while the `<img>` does as well is to unbind them and allow you to use whatever you want in the `default` slot. For instance, a simple case in which you would separate the image from the loader:
160
+
* Param: native load event
114
161
115
-
```html
116
-
<clazy-loadsrc="imgsrc">
117
-
<figureclass="image-wrapper">
118
-
<imgsrc="imgsrc">
119
-
</figure>
120
-
<divclass="preloader-wrapper"slot="placeholder">
121
-
<preloader-component></preloader-component>
122
-
</div>
123
-
</clazy-load>
124
-
```
162
+
Image finished loading and is now visible.
163
+
164
+
#### `error`
125
165
126
-
Another case would be to use transitions. Check out the [example](example/index.html) for details in using transitions.
166
+
* Param: native error event
127
167
128
-
### Scroll watching behavior
168
+
Could not load image. **Image is not shown, placeholder still visible.**
129
169
130
-
Clazy Load uses the new IntersectionObserver API to watch for element visibility on screen. This way it is not only optimized due to use native browser API, it has no proprietary code or gimmicks watching for scroll and making checks, so it will be easier to maintain.
170
+
### Compatibility
131
171
132
-
The downside is that this API is quite recent, so there still is small browser compatibility. Gladly, [Polyfill.io](https://polyfill.io/) covers this use case, and if you need to support older browsers, such as IE, you can include the following tag in your page:
172
+
Vue Clazy Load uses the Intersection Observer API to watch for the element visibility on screen. The advantages are native optimization from each browser and no need to implement a custom solution that may be buggy and increase file size. The only caveat to this approach is that this API is quite new, so older browsers do not support it.
173
+
174
+
If your application needs to be backwards compatible with IE and others, there are polyfills available. I personally recommend [Polyfill.io](https://polyfill.io/). You can check their documentation on how to add it to your website, or simply include the following tag if you're not using any other polyfills:
Or simply add `IntersectionObserver` to the `?features=` query of the URL if already using Polyfill.
139
-
140
-
The two configurable props `element` and `threshold` are bound to IntersectionObserver. `element` is used in a `document.querySelector` to pass the element to the `root` option, and `threshold` is used as it is. More details on those two options are available on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
0 commit comments