Have ideas to improve npm?Join in the discussion! »

    TypeScript icon, indicating that this package has built-in type declarations

    4.0.2 • Public • Published

    Vue Loading Overlay Component

    downloads jsdelivr npm-version github-tag build license ts

    Vue.js component for full screen loading indicator

    Demo or JSFiddle

    Version matrix

    Vue.js version Package version Branch
    2.x 3.x 3.x
    3.x 4.x master


    # yarn
    yarn add vue-loading-overlay@^4.0
    # npm
    npm install vue-loading-overlay@^4.0 


    As component

        <div class="vld-parent">
            <loading v-model:active="isLoading"
            <label><input type="checkbox" v-model="fullPage">Full page?</label>
            <button @click.prevent="doAjax">fetch Data</button>
        import Loading from 'vue-loading-overlay';
        import 'vue-loading-overlay/dist/vue-loading.css';
        export default {
            data() {
                return {
                    isLoading: false,
                    fullPage: true
            components: {
            methods: {
                doAjax() {
                    this.isLoading = true;
                    // simulate AJAX
                    setTimeout(() => {
                        this.isLoading = false
                    }, 5000)
                onCancel() {
                    console.log('User cancelled the loader.')

    As plugin

    • Install the plugin in your app
    import {createApp} from 'vue';
    import VueLoading from 'vue-loading-overlay';
    import 'vue-loading-overlay/dist/vue-loading.css';
    // Your app initialization logic goes here
    const app = createApp({}).mount('#app')
    • Then use the plugin in your components
        <form @submit.prevent="submit" 
            <!-- your form inputs goes here-->
            <label><input type="checkbox" v-model="fullPage">Full page?</label>
            <button type="submit">Login</button>
        export default {
            data() {
                return {
                    fullPage: false
            methods: {
                submit() {
                    let loader = this.$loading.show({
                        // Optional parameters
                        container: this.fullPage ? null : this.$refs.formContainer,
                        canCancel: true,
                        onCancel: this.onCancel,
                    // simulate AJAX
                    setTimeout(() => {
                    }, 5000)
                onCancel() {
                    console.log('User cancelled the loader.')

    Available props

    The component accepts these props:

    Attribute Type Default Description
    active Boolean false Show loading by default when true, use it as v-model:active
    can-cancel Boolean false Allow user to cancel by pressing ESC or clicking outside
    on-cancel Function ()=>{} Do something upon cancel, works in conjunction with can-cancel
    is-full-page Boolean true When false; limit loader to its container^
    transition String fade Transition name
    color String #000 Customize the color of loading icon
    height Number * Customize the height of loading icon
    width Number * Customize the width of loading icon
    loader String spinner Name of icon shape you want use as loader, spinner or dots or bars
    background-color String #fff Customize the overlay background color
    opacity Number 0.5 Customize the overlay background opacity
    z-index Number 9999 Customize the overlay z-index
    enforce-focus Boolean true Force focus on loader
    lock-scroll Boolean false Freeze the scrolling during full screen loader
    blur String 2px Value for the CSS blur backdrop-filter. Set to null or an empty string to disable blurring
    • ^When is-full-page is set to false, the container element should be positioned as position: relative. You can use CSS helper class vld-parent.
    • *The default height and width values may be varied based on the loader prop value

    Available slots

    The component accepts these slots:

    • default - Replace the animated icon with yours
    • before - Place anything before the animated icon, you may need to style this.
    • after - Place anything after the animated icon, you may need to style this.

    API methods


    import {h} from 'vue';
    let loader = this.$loading.show({
        // Pass props by their camelCased names
        container: this.$refs.loadingContainer,
        canCancel: true, // default false
        onCancel: this.yourCallbackMethod,
        color: '#000000',
        loader: 'spinner',
        width: 64,
        height: 64,
        backgroundColor: '#ffffff',
        opacity: 0.5,
        zIndex: 999,
    }, {
        // Pass slots by their names
        default: h('your-custom-loader-component-name'),
    // hide loader whenever you want

    Global configs

    You can set props and slots for all future instances when using as plugin

    app.use(VueLoading, {
        // props
        color: 'red'
    }, {
        // slots

    Further you can override any prop or slot when creating new instances

    let loader = this.$loading.show({
        color: 'blue'
    }, {
        // slots

    Install in non-module environments (without webpack)

    <!-- Vue js -->
    <script src="https://cdn.jsdelivr.net/npm/vue@3"></script>
    <!-- Lastly add this package -->
    <script src="https://cdn.jsdelivr.net/npm/vue-loading-overlay@4"></script>
    <link href="https://cdn.jsdelivr.net/npm/vue-loading-overlay@4/dist/vue-loading.css" rel="stylesheet">
    <!-- Init the plugin and component-->
        const app = Vue.createApp({}).mount('#app')
        app.component('loading', VueLoading)

    Browser support

    • Modern browsers only

    Run examples on your localhost

    • Clone this repo
    • Make sure you have node-js >=12.14 and yarn >=1.x pre-installed
    • Install dependencies - yarn install
    • Run webpack dev server - yarn start
    • This should open the demo page at http://localhost:9000 in your default web browser


    • This package is using Jest and vue-test-utils for testing.
    • Tests can be found in __test__ folder.
    • Execute tests with this command yarn test


    MIT License


    npm i vue-loading-overlay

    DownloadsWeekly Downloads






    Unpacked Size

    59.9 kB

    Total Files


    Last publish


    • avatar