Vue 3 Spinners

Common errors

• Failed to resolve component: VueSpinnerXXX

  cause The spinner component was not correctly imported or registered in the Vue application or local component.
  fix Ensure you have `import { VueSpinnerXXX } from 'vue3-spinners';` in your script block and either listed in the `components` option (for Options API) or directly used in the template (for `<script setup>`). For global registration, verify `app.use(VueSpinnersPlugin);` is called in your main.ts/main.js file.

• Property 'someUnknownProp' was accessed during render but is not defined on instance.

  cause Attempting to pass a prop that is not recognized or accepted by the specific spinner component.
  fix Check the documentation or source code for the specific spinner component you are using to confirm its supported props. Ensure you are only passing valid props like `color`, `size`, or other component-specific ones.

Warnings

• gotcha This `vue3-spinners` package is specifically for Vue 3. An older, unmaintained package named `vue-spinners` exists for Vue 2.x and should not be used in modern Vue 3 applications. Ensure you install `vue3-spinners` to avoid compatibility issues.
  Fix: Always use `npm install vue3-spinners` or `yarn add vue3-spinners` for Vue 3 projects.
• gotcha Spinners have a set of 'universal props' (like `color` and `size`) and 'spinner-dependent props' (like `height`, `width`, `radius`, `margin`) that vary by the specific spinner component. Using a spinner-dependent prop on a spinner that doesn't support it will have no effect or may cause console warnings.
  Fix: Consult the package's GitHub documentation (https://github.com/leonsilicon/vue3-spinners/tree/main/packages/vue3-spinners/src/spinners) to verify which props are accepted by each individual spinner component.
• gotcha While `vue3-spinners` components can be used as fallback content within Vue 3's built-in `<Suspense>` component, understand that `<Suspense>` is primarily designed to orchestrate asynchronous *component dependencies* (e.g., `async setup()` or `defineAsyncComponent`), not just generic loading states. Misunderstanding its purpose can lead to complex and unnecessary wrapper logic.
  Fix: Use `<Suspense>` when you need to wait for multiple asynchronous child components to resolve before showing content. For simpler data fetching or state-driven loading, a `v-if` or `v-show` with a local spinner component is often sufficient and more straightforward.

Install

• npm install vue3-spinners npm
• yarn add vue3-spinners yarn
• pnpm add vue3-spinners pnpm

Imports

• VueSpinnerCube
  wrong:

  import VueSpinnerCube from 'vue3-spinners'

  correct:

  import { VueSpinnerCube } from 'vue3-spinners'

  All individual spinner components are named exports, not default exports. Ensure you use curly braces for destructuring.
• VueSpinnersPlugin
  wrong:

  const VueSpinnersPlugin = require('vue3-spinners').VueSpinnersPlugin

  correct:

  import { VueSpinnersPlugin } from 'vue3-spinners'

  The library primarily targets ESM environments for modern Vue 3 development. Use standard ES module imports.
• All Spinners (example: VueSpinnerHourglass)
  wrong:

  import { SpinnerHourglass } from 'vue3-spinners'

  correct:

  import { VueSpinnerHourglass } from 'vue3-spinners'

  Each spinner component is prefixed with 'VueSpinner'. Incorrectly omitting 'Vue' will result in a module not found error.

Quickstart

This quickstart demonstrates how to import and conditionally render a specific spinner (`VueSpinnerBars`) in a Vue 3 component using `<script setup>`, simulating a data loading process. It showcases basic prop usage for size and color.

<!-- src/components/MyLoadingComponent.vue -->
<template>
  <div v-if="isLoading" class="loading-overlay">
    <VueSpinnerBars :size="spinnerSize" :color="spinnerColor" />
    <p class="loading-text">Loading data...</p>
  </div>
  <div v-else>
    <!-- Your loaded content here -->
    <p>Data loaded successfully!</p>
    <button @click="simulateLoading">Reload Data</button>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { VueSpinnerBars } from 'vue3-spinners';

const isLoading = ref(true);
const spinnerSize = ref(50); // in pixels
const spinnerColor = ref('#42b983'); // Vue green

const simulateLoading = () => {
  isLoading.value = true;
  // Simulate an asynchronous operation (e.g., API call)
  setTimeout(() => {
    isLoading.value = false;
  }, 2000);
};

onMounted(() => {
  simulateLoading(); // Trigger loading on component mount
});
</script>

<style scoped>
.loading-overlay {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  height: 200px;
  gap: 15px;
  background-color: #f0f0f0;
  border-radius: 8px;
  margin-top: 20px;
}
.loading-text {
  font-family: sans-serif;
  color: #333;
  font-size: 1.1em;
}
button {
  padding: 10px 20px;
  font-size: 1em;
  color: white;
  background-color: #42b983;
  border: none;
  border-radius: 5px;
  cursor: pointer;
  margin-top: 20px;
}
button:hover {
  background-color: #368a6f;
}
</style>