Vue Spinner Components

3.0.1 · active · verified Sun Apr 19

vue-spinner is a collection of 16 highly customizable loading spinner components for Vue.js applications. Currently at version 3.0.1, it specifically targets Vue 3.5+ using the Composition API, offering full TypeScript support with detailed prop types, and ships with ESM and UMD outputs for broad compatibility. The library differentiates itself by providing a variety of pre-built, production-ready spinners based on the Halogen project, covering common loading patterns with props for `loading` state, `color`, `size` (or `height`/`width`), `margin`, and `radius`. While it recently underwent a major overhaul for Vue 3 compatibility, previous versions (like 1.0.4) are available for Vue 1.x projects, establishing a clear versioning strategy tied to Vue's major releases. The project appears to have an active maintenance cadence, with recent updates adding significant test coverage via Vitest.

Common errors

```
Failed to resolve component: <component-name>
```
cause The spinner component was not correctly imported or registered with the Vue application.

fix Ensure you either use a named import like `import { PulseLoader } from 'vue-spinner'` and list it in `components: { PulseLoader }`, or globally register it with `app.component('PulseLoader', PulseLoader)`.
```
[Vue warn]: Component <Component> is missing template or render function.
```
cause Attempting to import a `.vue` file component directly in an environment that doesn't support Vue SFC compilation (e.g., a vanilla JS file without a build step, or a mismatched bundler configuration).

fix When importing individual components like `import PulseLoader from 'vue-spinner/src/PulseLoader.vue'`, ensure your build setup (Vite, Webpack) is correctly configured to process `.vue` Single File Components. For most cases, `import { PulseLoader } from 'vue-spinner'` is preferred as it imports the pre-compiled component.

Warnings

breaking Version 3.x of vue-spinner is a complete rewrite for Vue 3.x and is incompatible with Vue 1.x.
Fix: For Vue 1.x projects, use `vue-spinner@1.0.4`. For Vue 3.x projects, ensure your Vue version is 3.5.0 or higher. Migrate your component usage to the Vue 3 Composition API where applicable.
gotcha While many spinners use a `size` prop, some like `FadeLoader` and `ScaleLoader` use `height` and `width` instead. Check the documentation for specific spinner props.
Fix: Always consult the 'Props' section in the documentation or the component's TypeScript definitions to determine the correct sizing props for each spinner component.
gotcha Global CSS styles could potentially conflict with the spinner styles if not properly scoped. Although `vue-spinner` v3 now uses scoped CSS, external styles might still interfere.
Fix: If experiencing unexpected styling, inspect the elements to check for conflicting CSS rules. Use more specific CSS selectors or consider CSS Modules/scoped styles in your own components to avoid global clashes.

Install

npm install vue-spinner npm
yarn add vue-spinner yarn
pnpm add vue-spinner pnpm

Imports

PulseLoader
wrong:
```
const PulseLoader = require('vue-spinner')
```
correct:
```
import { PulseLoader } from 'vue-spinner'
```
This is the recommended ES Module import for named components. CommonJS `require` is not supported for individual components directly from the main bundle in v3.
PulseLoader
```
import PulseLoader from 'vue-spinner/src/PulseLoader.vue'
```
Direct import of a single Vue component file. Useful for tree-shaking or when you only need a specific spinner.
VueSpinner
```
const { PulseLoader, GridLoader } = VueSpinner
```
Available in browser environments when using the UMD build (`vue-spinner.umd.js`), which exposes a global `VueSpinner` object.
types
```
import type { PulseLoaderProps } from 'vue-spinner'
```
Since v3.0.1, the package ships with full TypeScript declarations for all components and their props.

Quickstart

Demonstrates importing and using the PulseLoader component in a Vue 3 setup script, managing its loading state and custom props.

import { ref } from 'vue'
import { PulseLoader } from 'vue-spinner'

const App = {
  setup() {
    const loading = ref(true)
    const color = ref('#5dc596')
    const size = ref('15px')

    // Simulate loading state change after a few seconds
    setTimeout(() => {
      loading.value = false;
    }, 3000);

    return {
      loading,
      color,
      size
    }
  },
  template: `
    <div style="display: flex; justify-content: center; align-items: center; min-height: 100px;">
      <pulse-loader :loading="loading" :color="color" :size="size"></pulse-loader>
      <p v-if="!loading" style="margin-left: 10px;">Content Loaded!</p>
    </div>
  `,
  components: { PulseLoader }
}

// In a real Vue app, you would mount this:
// import { createApp } from 'vue'
// createApp(App).mount('#app')

view raw JSON →