Vue FilePond Adapter

Common errors

• Failed to resolve component: file-pond or [Vue warn]: Unknown custom element: <FilePond>

  cause The FilePond component was not correctly registered with Vue, or the `vueFilePond` factory was not called to create the component.
  fix Ensure you import `vueFilePond`, call it with necessary plugins (e.g., `const FilePond = vueFilePond();`), and then register this `FilePond` constant in your component's `components` option.

• Cannot read properties of undefined (reading 'registerPlugin') or FilePond is not a constructor

  cause FilePond plugins were passed directly as props to the `<FilePond>` component instead of being passed as arguments to the `vueFilePond` factory function, or the factory function itself wasn't called.
  fix Plugins should be passed as arguments to the `vueFilePond` function when creating the component: `const FilePond = vueFilePond(Plugin1, Plugin2);`.

• Module not found: Error: Can't resolve 'filepond/dist/filepond.min.css'

  cause The `filepond` package or its styles are not installed or correctly resolved by your bundler.
  fix Run `npm install filepond` and ensure the import path `import "filepond/dist/filepond.min.css";` is correct and accessible within your project's module resolution configuration.

• [Vue warn]: Hydration completed but contains mismatches. (in SSR environments like Nuxt.js)

  cause FilePond's client-side rendering conflicts with the server-side rendered HTML, leading to hydration errors.
  fix Wrap the `<file-pond>` component in a `<no-ssr>` tag or use client-only rendering strategies specific to your SSR framework to ensure it's rendered only on the client side.

Warnings

• breaking Version 7.x+ of `vue-filepond` is exclusively compatible with Vue 3. Applications using Vue 2 must install `vue-filepond@^6.0.0`.
  Fix: For Vue 2 projects, run `npm install vue-filepond@^6.0.0`. For Vue 3 projects, ensure you are on `vue-filepond@^7.0.0` or higher.
• gotcha FilePond plugins (e.g., image preview, file type validation) are not bundled with `vue-filepond` and must be installed, imported, and registered separately when creating the FilePond component.
  Fix: Install required plugins via npm (e.g., `npm install filepond-plugin-image-preview`), then import and pass them as arguments to the `vueFilePond` factory function: `const FilePond = vueFilePond(Plugin1, Plugin2);`.
• gotcha Core FilePond styles (`filepond.min.css`) and any plugin-specific styles must be explicitly imported into your project to ensure correct rendering.
  Fix: Add `import "filepond/dist/filepond.min.css";` and any plugin styles (e.g., `import "filepond-plugin-image-preview/dist/filepond-plugin-image-preview.min.css";`) to your main entry file or component's style block.
• gotcha When using Server-Side Rendering (SSR) frameworks like Nuxt.js, the FilePond component should be wrapped in `<no-ssr>` tags or similar client-only hydration logic to prevent build issues or hydration mismatches.
  Fix: Wrap the `<FilePond />` component in a `<no-ssr>` component or use dynamic imports with `ssr: false` in your Nuxt.js configuration to ensure client-side rendering.
• gotcha In older versions (`<=5.1.2`), there was a known issue where FilePond's detach mechanism would not run correctly, potentially leading to memory leaks. This was fixed in v5.1.3 and subsequent versions.
  Fix: Upgrade to `vue-filepond` version 5.1.3 or higher to benefit from the memory leak fix and improve application stability.

Install

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

Imports

• vueFilePond
  wrong:

  const vueFilePond = require("vue-filepond");

  correct:

  import vueFilePond from "vue-filepond";

  This is the factory function used to create the FilePond Vue component. It should be imported for ESM.
• FilePondPluginFileValidateType
  wrong:

  const FilePondPluginFileValidateType = require("filepond-plugin-file-validate-type");

  correct:

  import FilePondPluginFileValidateType from "filepond-plugin-file-validate-type";

  FilePond plugins must be imported separately and then passed to the `vueFilePond` factory function.
• FilePond base styles
  wrong:

  require("filepond/dist/filepond.min.css");

  correct:

  import "filepond/dist/filepond.min.css";

  The core FilePond CSS styles are essential for the component's appearance and must be imported.
• FilePond component

  const FilePond = vueFilePond(FilePondPluginFileValidateType, FilePondPluginImagePreview);

  The actual Vue component named 'FilePond' is created by calling the `vueFilePond` factory function, optionally with any desired FilePond plugins as arguments.

Quickstart

This example demonstrates how to set up the FilePond component, register plugins, handle initial files, and listen to events in a Vue 3 application.

<template>
  <div id="app">
    <file-pond
      name="test"
      ref="pond"
      label-idle="Drop files here..."
      v-bind:allow-multiple="true"
      accepted-file-types="image/jpeg, image/png"
      server="/api"
      v-bind:files="myFiles"
      v-on:init="handleFilePondInit"
    />
  </div>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import vueFilePond from "vue-filepond";
import "filepond/dist/filepond.min.css";
import "filepond-plugin-image-preview/dist/filepond-plugin-image-preview.min.css";
import FilePondPluginFileValidateType from "filepond-plugin-file-validate-type";
import FilePondPluginImagePreview from "filepond-plugin-image-preview";

const FilePond = vueFilePond(
  FilePondPluginFileValidateType,
  FilePondPluginImagePreview
);

export default defineComponent({
  name: "app",
  components: {
    FilePond,
  },
  data() {
    return { myFiles: ["cat.jpeg"] };
  },
  methods: {
    handleFilePondInit() {
      console.log("FilePond has initialized");
      // FilePond instance methods are available on `this.$refs.pond`
    },
  },
});
</script>