Vue Image Loader Component

Common errors

• [Vue warn]: Unknown custom element: <vue-load-image>

  cause The `vue-load-image` component was not properly imported or registered in the Vue component where it's being used.
  fix Ensure you have `import VueLoadImage from 'vue-load-image';` in your script and `components: { 'vue-load-image': VueLoadImage }` in your component's options or registered globally using `Vue.component('vue-load-image', VueLoadImage);` in your main.js file.

• GET http://localhost:8080/image.png 404 (Not Found)

  cause The image `src` provided to the `img` tag within the `image` slot is incorrect or the image file does not exist at the specified path, especially when dealing with local assets in a Vue CLI project.
  fix Double-check the image path. For images in `src/assets`, use `require('./assets/image.png')` or import them directly. For images in the `public` directory, use an absolute path like `/image.png`. Verify the image file exists and its filename matches exactly.

• The preloader doesn't appear, or the image just flashes briefly before loading.

  cause The preloader image/content is either not styled correctly to be visible, or the main image loads too quickly for the preloader to be meaningfully displayed, often due to local caching or very fast network conditions.
  fix Ensure your preloader content has distinct styling (e.g., background color, `width`, `height`, `text-align: center`). You can temporarily add a `setTimeout` around the image `src` assignment in the component's internal logic (if modifying source) or simulate network delay in browser developer tools to observe the preloader behavior. For very fast loads, the preloader might intentionally be skipped or barely visible as part of a good UX.

Warnings

• breaking This version (0.2.0) is built for Vue 2.x, which reached End-of-Life (EOL) in December 2023. Using this package in a new Vue 3 project will lead to incompatibility and runtime errors due to breaking changes in Vue's API between major versions.
  Fix: For Vue 3 projects, consider using `vue-load-image@next` (if actively maintained) or alternative image loading solutions designed for Vue 3. For existing Vue 2 projects, be aware of security implications of using EOL software.
• gotcha Dynamic image paths (e.g., from data or props) in Vue 2 often require specific handling with `require()` or `new URL()` within templates or script blocks, especially when images are located in the `src/assets` directory and processed by webpack/Vue CLI. Directly using a string path like `src="./assets/my-image.png"` might not work in production builds.
  Fix: For local assets, use `require('./assets/my-image.png')` within your data properties or computed properties, or ensure paths are correctly resolved by your build tool. For dynamic public assets, place them in the `public` folder and reference them from the root, e.g., `/img/my-image.png`.
• deprecated The component itself shows no active maintenance for the Vue 2.x branch since approximately five years ago, aligning with the end of Vue 2 support. This means no new features, bug fixes, or security patches will be released for this version.
  Fix: Evaluate the need for this specific functionality against the risks of using unmaintained software. Consider migrating to a more actively maintained Vue 3 compatible library for image loading, or implementing similar functionality manually if the project requires long-term support.
• gotcha Styling the preloader and error slots requires careful consideration. The default component provides structural slots, but no inherent styling. Developers must apply their own CSS to ensure the loader is visible, centered, and visually appealing, and that the error message is clearly formatted.
  Fix: Apply custom CSS to the elements within the `preloader` and `error` slots. Use `display: block; margin: auto;` or flexbox/grid for centering. Ensure appropriate `width`, `height`, and `background` styles are set for visual feedback during loading.

Install

• npm install vue-load-image npm
• yarn add vue-load-image yarn
• pnpm add vue-load-image pnpm

Imports

• VueLoadImage
  wrong:

  import { VueLoadImage } from 'vue-load-image';

  correct:

  import VueLoadImage from 'vue-load-image';

  The component is exported as a default export, so curly braces should not be used for direct import.
• Component Registration (Local)
  wrong:

  export default {
    components: { VueLoadImage }
  }

  correct:

  export default {
    components: { 'vue-load-image': VueLoadImage }
  }

  While shorthand registration `VueLoadImage` might work, explicitly naming it `'vue-load-image'` aligns with the conventional usage demonstrated in the package's documentation for Vue 2.x templates.
• Component Registration (Global)
  wrong:

  Vue.component(VueLoadImage.name, VueLoadImage);

  correct:

  import VueLoadImage from 'vue-load-image';
  Vue.component('vue-load-image', VueLoadImage);

  Global registration directly registers the component under the specified tag name, making it available throughout your Vue instance without local import in every component.

Quickstart

This quickstart demonstrates the basic usage of `vue-load-image` in a Vue 2.x application. It shows how to import and register the component, and then use its `image`, `preloader`, and `error` slots to display different content based on the image loading state, including a successful load and an intentional error scenario.

<!-- App.vue (or any Vue 2 component) -->
<template>
  <div id="app">
    <h1>Image Loading Demo</h1>
    <p>Using vue-load-image to display a loader while images load.</p>

    <h2>Example 1: Basic Image with Preloader and Error Slot</h2>
    <vue-load-image>
      <template v-slot:image>
        <img src="https://via.placeholder.com/400x200?text=Loaded+Image" alt="Loaded Image" />
      </template>
      <template v-slot:preloader>
        <img src="https://i.imgur.com/gKj31sO.gif" alt="Loading..." style="width: 100px; height: 100px;" />
      </template>
      <template v-slot:error>
        <div style="color: red; border: 1px solid red; padding: 10px;">Failed to load image!</div>
      </template>
    </vue-load-image>

    <h2>Example 2: Image with an intentionally broken URL</h2>
    <vue-load-image>
      <template v-slot:image>
        <img src="/non-existent-image.jpg" alt="Broken Image" />
      </template>
      <template v-slot:preloader>
        <p>Loading broken image...</p>
      </template>
      <template v-slot:error>
        <div style="background-color: #ffe0e0; padding: 10px;">Oops! This image couldn't be found.</div>
      </template>
    </vue-load-image>
  </div>
</template>

<script>
import VueLoadImage from 'vue-load-image';

export default {
  name: 'App',
  components: {
    'vue-load-image': VueLoadImage // Registering the component locally
  }
};
</script>

<style>
#app {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-align: center;
  color: #2c3e50;
  margin-top: 60px;
}
.vue-load-image {
  display: inline-block;
  margin: 20px;
  border: 1px solid #ccc;
  padding: 10px;
}
</style>