Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/subotkevic/vue-lazy-image-loading
Vue lazy image and background loading plugin.
https://github.com/subotkevic/vue-lazy-image-loading
background image lazy-images lazy-loading placeholder-image vue
Last synced: about 2 months ago
JSON representation
Vue lazy image and background loading plugin.
- Host: GitHub
- URL: https://github.com/subotkevic/vue-lazy-image-loading
- Owner: subotkevic
- License: mit
- Created: 2018-11-09T13:05:14.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-30T02:10:08.000Z (over 1 year ago)
- Last Synced: 2024-07-13T10:45:00.463Z (2 months ago)
- Topics: background, image, lazy-images, lazy-loading, placeholder-image, vue
- Language: JavaScript
- Homepage:
- Size: 6.12 MB
- Stars: 330
- Watchers: 9
- Forks: 12
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Vue Lazy Image Loading
Vue progressive image and background loading plugin.
## Installation
```bash
npm install vue-lazy-image-loading
```
## Usage
```js
import Vue from 'vue'
import VueLazyImageLoading from 'vue-lazy-image-loading'
Vue.use(VueLazyImageLoading)
```
#### Lazy image
Instead of using the normal `img` tag to load images
```html
```
use the `lazy-img` component already globally available after the plugin installation
```html
```
#### Lazy background
It is also possible to apply lazy images as backgrounds and it will have the same props as the lazy-img component
```html
```
## Global properties
There is all properties you can use for both `lazy-img` and `lazy-background` components.
### Placeholder
To be able to immediately show some feedback to the user, it is possible to pass a placeholder image, which could be also 1% the size of the main image: it will be blurred so you can go crazy with optimizations here.
In this example I actually use the same image, but you have the idea here
```html
```
### Blur
It is possible to adjust the level of blur applied to the placeholder image
```html
```
### Ratio
It is possible to remove the padding that adds the aspect ratio to the container.
```html
```
It is also possible to manually specify the image aspact ratio when you know it. It allows the placeholder to be displayed in the correct aspect ratio. The ratio is calculated as `height / width`.
```html
```
## `lazy-background` properties
There is all properties you can use for the `lazy-background` component only.
### Background position
Allows you to set the value of the `background-position` CSS property.
The default value is `0% 0%`.
```html
```
### Background size
Allows you to set the value of the `background-size` CSS property.
The default value is `cover`.
```html
```
### Background repeat
Allows you to set the value of the `background-repeat` CSS property.
The default value is `no-repeat`.
```html
```
### The slot
The lazy-background has a "content" slot, which can hold content that needs to be rendered over the background image and also can hold a preloader.
This slot has one property called "visible" that tells you when, for example, a preloader needs to be visible or not.
```html
I am some content to display over the image
I am the preloader
```
## Image fallback
In case of a loading error of the main image, it is possible to add a fallback image which can display an error image or just another image.
```html
```
## Vue Loader - Asset URL Handling
If you're using Vue Loader, it's Asset URL transforms will not work with our `lazy-img` and `lazy-background` elements by default.
By default the following tag/attribute combinations are transformed, and can be configured using the [transformAssetUrls](https://vue-loader.vuejs.org/options.html#transformasseturls) option:
```js
{
video: ['src', 'poster'],
source: 'src',
img: 'src',
image: 'xlink:href'
}
```
All you have to is to add our `lazy-img` and `lazy-background` tags to the `transformAssetUrls` object:
```js
{
video: ['src', 'poster'],
source: 'src',
img: 'src',
image: 'xlink:href',
'lazy-img': 'src',
'lazy-background': 'src'
}
```
Now, Vue Loader's Asset URL transforms will work with our elements too.
## Events
Each component emits an event whenever an image is loaded.
Because we usually load two images, a main image and a placeholder, two events are dispatched `onLoad` and `onLoadPlaceholder`
in your js file
```js
export default {
methods: {
onLoad () {
// main image is loaded
},
onLoadPlaceholder () {
// placeholder image is loaded
},
onError (error) {
// main image error
},
onErrorPlaceholder (error) {
// placeholder image error
}
}
}
```
in the html just add the events you need to listen to
```html
```
## Options
During the installation process it is possible to pass some default global options
#### Cached images
* type: Boolean
* default: true
Cached images are checked by default. This check kills the animation if the image was already loaded once.
If you would like to show the animation every time, even when is not needed, you can simply use the plugin options like so:
```js
Vue.use(VueLazyImageLoading, {
cache: false
})
```
#### placeholder
* type: String
* required: false
```js
Vue.use(VueLazyImageLoading, {
placeholder: 'https://unsplash.it/1920/1080?image=20'
})
```
#### blur
* type: Number
* required: false
* default: 5
```js
Vue.use(VueLazyImageLoading, {
blur: 30
})
```
#### delay
* type: Number
* default: 0
This options is for debug only. It lets you have an easy look at the placeholder before the main image is fully loaded.
```js
Vue.use(VueLazyImageLoading, {
delay: 2000 // 2 seconds before the image is displayed
})
```
#### position
* type: String
* default: '0% 0%'
Allows you to set the value of the `background-position` CSS property.
Will only work `lazy-background` component.
```js
Vue.use(VueLazyImageLoading, {
position: 'center'
})
```
#### size
* type: String
* default: 'cover'
Allows you to set the value of the `background-size` CSS property.
Will only work `lazy-background` component.
```js
Vue.use(VueLazyImageLoading, {
size: 'contain'
})
```
#### repeat
* type: String
* default: 'no-repeat'
Allows you to set the value of the `background-repeat` CSS property.
Will only work `lazy-background` component.
```js
Vue.use(VueLazyImageLoading, {
repeat: 'repeat-x'
})
```
**Global options like `placeholder` and `blur` will be applied only to components that don't specify their own options**