Vue3-progress: Lightweight progress bar for vue 3

Vue3-progress is a vue3 plugin to show a progress bar while waiting for something.

View a working demo on https://vue3-progress-demo.netlify.app

Getting Started

Installation

//npm

npm install @marcoschulte/vue3-progress

Register plugin globally

// main.ts

import {createApp} from 'vue';
import App from './App.vue';
import {Vue3ProgressPlugin} from '@marcoschulte/vue3-progress';

createApp(App)
    .use(Vue3ProgressPlugin)
    .mount('#app');

register scss file

// in an .scss file
@import "~@marcoschulte/vue3-progress/dist/";

// alternatively the pre-compiled css can be imported from @marcoschulte/vue3-progress/dist/index.css

Usage

Add progress bar component

//~App.vue

<template>
  <vue3-progress-bar></vue3-progress-bar>

</template>

There are different ways to use the plugin

import {useProgress} from '@marcoschulte/vue3-progress';

// via useProgress()
const progress = useProgress().start();
progress.finish();

// via global property
const progress = this.$progress.start();
progress.finish();

Alternatively the progress plugin can be attached to a Promise

const promise: Promise<any> = loadUsers();
const attached = useProgess().attach(promise);
const thisIsTrue = attached === promise;

Multiple simultaneous progresses

// the plugin tracks how many "progresses" are active.
// progress.finish() can safely be called multiple times
const progress1 = useProgress().start(); // progress bar appears
const progress2 = useProgress().start();

progress1.finish();
progress1.finish(); // progress bar is still shown, calling multiple times is safe
progress2.finish(); // progress bar disappears

On the scope of useProgress()

useProgress() can be used from everywhere, not only from vue functional components such as setup. This is possible because a reference to the plugins instance is globally registered. This behavior can be deactivated through installing the plugin as .use(Vue3ProgressPlugin, {disableGlobalInstance: true}). The plugin will now use Vue.js inject/provide mechanism.

Example with axios

import {ProgressFinisher, useProgress} from '@marcoschulte/vue3-progress';

const progresses = [] as ProgressFinisher[];

axios.interceptors.request.use(config => {
  progresses.push(useProgress().start());
  return config;
});

axios.interceptors.response.use(resp => {
  progresses.pop()?.finish();
  return resp;
}, (error) => {
  progresses.pop()?.finish();
  return Promise.reject(error);
});

Customizations

Customizing the style

Some scss variables are exposed which can be customized as follows. Check ProgressBar.vue for all variables.

$vue3-progress-bar-color: #ff0000;
@import "~@marcoschulte/vue3-progress/dist/";

Alternatively the css classes can be overridden en in your own style.

Customizing the ProgressBar Component

If customizing the style is not sufficient, you can easily write your own progress bar component instead of using the provided one. The trickling effect can be reused if wanted, it is provided as a composable. Check ProgressBar.vue as a reference to create your own.

Github: https://github.com/marcoschulte/vue3-progress