Vue Loaders

Common errors

• [Vue warn]: Unknown custom element: <vue-loaders-ball-beat> - did you register the component correctly?

  cause The loader component was not globally registered via `Vue.use(VueLoaders)` or locally registered within the Vue component where it's being used.
  fix Add `Vue.use(VueLoaders);` to your application's entry file (e.g., `main.js` or `main.ts`), or import specific loaders and register them in your component's `components` option: `{ components: { VueLoadersBallBeat } }`.

• Loader appears as static dots/shapes, no animation or incorrect styling.

  cause The required `vue-loaders/dist/vue-loaders.css` stylesheet was not properly imported or linked in the application.
  fix Ensure `import 'vue-loaders/dist/vue-loaders.css';` is included in your main JavaScript/TypeScript file or that the CSS file is otherwise correctly loaded by your build system.

Warnings

• breaking Version 4.0.0 introduced breaking changes by adding initial support for Vue 3. Projects using Vue 2 should remain on v3.x.x to avoid compatibility issues, or migrate their application to Vue 3.
  Fix: For Vue 2 projects, use `npm install vue-loaders@^3` to explicitly install the latest Vue 2 compatible version. For Vue 3 projects, upgrade to v4.x.x.
• gotcha Forgetting to import the `vue-loaders.css` stylesheet will result in loaders appearing as static, unstyled elements without animation, making them effectively invisible or broken.
  Fix: Ensure `import 'vue-loaders/dist/vue-loaders.css';` is present in your application's entry point (e.g., `main.js`/`main.ts`) or properly linked in your HTML/main stylesheet.
• gotcha While `Vue.use(VueLoaders)` is convenient for global registration of all loaders, it might lead to a larger bundle size if only a few specific loaders are needed. Consider importing and registering individual components locally for better tree-shaking.
  Fix: Instead of `Vue.use(VueLoaders)`, import specific loaders like `import VueLoadersBallBeat from 'vue-loaders/dist/loaders/ball-beat';` and register them in your component's `components` option: `{ components: { VueLoadersBallBeat } }`.
• gotcha The `color` prop directly sets the loader's color. If you want the loader to inherit its color from a parent element's text color, you must explicitly set the `color` prop to `'currentColor'`.
  Fix: Use `<vue-loaders name="ball-beat" color="currentColor"></vue-loaders>` if you intend for the loader to dynamically inherit its color from its parent container's CSS `color` property.

Install

• npm install vue-loaders npm
• yarn add vue-loaders yarn
• pnpm add vue-loaders pnpm

Imports

• VueLoaders
  wrong:

  const VueLoaders = require('vue-loaders');

  correct:

  import VueLoaders from 'vue-loaders';

  This imports the main plugin. It is typically used with `Vue.use(VueLoaders)` to globally register all loader components. Modern Vue applications primarily use ESM imports.
• VueLoadersBallBeat
  wrong:

  import { VueLoadersBallBeat } from 'vue-loaders';

  correct:

  import VueLoadersBallBeat from 'vue-loaders/dist/loaders/ball-beat';

  For selective imports, individual loader components are imported directly from their respective paths. This allows for local component registration and can help optimize bundle size by only including necessary loaders.
• CSS Styles
  wrong:

  import 'loaders.css/loaders.min.css';

  correct:

  import 'vue-loaders/dist/vue-loaders.css';

  This CSS import is crucial for the visual styling and animations of all `vue-loaders` components. It must be included once in your application's entry point or main stylesheet for loaders to render correctly.

Quickstart

This example demonstrates how to register all loaders globally using `Vue.use(VueLoaders)` and then utilize both the dedicated component syntax (`<vue-loaders-ball-beat>`) and the dynamic `name` prop approach (`<vue-loaders name="ball-beat">`). It also includes the necessary CSS import for styling.

import Vue from 'vue/dist/vue.esm.browser';
import 'vue-loaders/dist/vue-loaders.css';
import VueLoaders from 'vue-loaders';

Vue.use(VueLoaders);

const template = `
<div>
  <vue-loaders-ball-beat color="red" scale="1"></vue-loaders-ball-beat>
  <hr/>
  <vue-loaders name="ball-beat" color="red" scale="1"></vue-loaders>
</div>
`;

new Vue({
  template
}).$mount('#app');