{"id":12473,"library":"vue-filepond","title":"Vue FilePond Adapter","description":"Vue FilePond is an official adapter component designed to integrate the powerful FilePond file upload library with Vue.js applications. Currently stable at version 7.0.4, this package provides a `FilePond` Vue component that wraps the underlying JavaScript library, enabling seamless file uploading experiences. While there isn't a strict release cadence, minor updates and bug fixes are released as needed. Its key differentiators include leveraging FilePond's robust feature set, such as drag-and-drop functionality, image optimization, accessibility features (keyboard navigation, AT software compatibility), responsive design, and support for various file types and upload methods (AJAX, base64, remote URLs). It's primarily designed for Vue 3, with a separate major version (v6) dedicated to Vue 2 support, ensuring broad compatibility while maintaining a modern API for newer Vue applications.","status":"active","version":"7.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/pqina/vue-filepond","tags":["javascript","vue","vuejs","filepond","file","upload","drag","drop","browse","typescript"],"install":[{"cmd":"npm install vue-filepond","lang":"bash","label":"npm"},{"cmd":"yarn add vue-filepond","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-filepond","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core FilePond library is required for all functionality.","package":"filepond","optional":false},{"reason":"Vue.js runtime is required, specifically Vue 3 for v7+.","package":"vue","optional":false}],"imports":[{"note":"This is the factory function used to create the FilePond Vue component. It should be imported for ESM.","wrong":"const vueFilePond = require(\"vue-filepond\");","symbol":"vueFilePond","correct":"import vueFilePond from \"vue-filepond\";"},{"note":"FilePond plugins must be imported separately and then passed to the `vueFilePond` factory function.","wrong":"const FilePondPluginFileValidateType = require(\"filepond-plugin-file-validate-type\");","symbol":"FilePondPluginFileValidateType","correct":"import FilePondPluginFileValidateType from \"filepond-plugin-file-validate-type\";"},{"note":"The core FilePond CSS styles are essential for the component's appearance and must be imported.","wrong":"require(\"filepond/dist/filepond.min.css\");","symbol":"FilePond base styles","correct":"import \"filepond/dist/filepond.min.css\";"},{"note":"The actual Vue component named 'FilePond' is created by calling the `vueFilePond` factory function, optionally with any desired FilePond plugins as arguments.","symbol":"FilePond component","correct":"const FilePond = vueFilePond(FilePondPluginFileValidateType, FilePondPluginImagePreview);"}],"quickstart":{"code":"<template>\n  <div id=\"app\">\n    <file-pond\n      name=\"test\"\n      ref=\"pond\"\n      label-idle=\"Drop files here...\"\n      v-bind:allow-multiple=\"true\"\n      accepted-file-types=\"image/jpeg, image/png\"\n      server=\"/api\"\n      v-bind:files=\"myFiles\"\n      v-on:init=\"handleFilePondInit\"\n    />\n  </div>\n</template>\n\n<script lang=\"ts\">\nimport { defineComponent } from 'vue';\nimport vueFilePond from \"vue-filepond\";\nimport \"filepond/dist/filepond.min.css\";\nimport \"filepond-plugin-image-preview/dist/filepond-plugin-image-preview.min.css\";\nimport FilePondPluginFileValidateType from \"filepond-plugin-file-validate-type\";\nimport FilePondPluginImagePreview from \"filepond-plugin-image-preview\";\n\nconst FilePond = vueFilePond(\n  FilePondPluginFileValidateType,\n  FilePondPluginImagePreview\n);\n\nexport default defineComponent({\n  name: \"app\",\n  components: {\n    FilePond,\n  },\n  data() {\n    return { myFiles: [\"cat.jpeg\"] };\n  },\n  methods: {\n    handleFilePondInit() {\n      console.log(\"FilePond has initialized\");\n      // FilePond instance methods are available on `this.$refs.pond`\n    },\n  },\n});\n</script>\n","lang":"typescript","description":"This example demonstrates how to set up the FilePond component, register plugins, handle initial files, and listen to events in a Vue 3 application."},"warnings":[{"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.","message":"Version 7.x+ of `vue-filepond` is exclusively compatible with Vue 3. Applications using Vue 2 must install `vue-filepond@^6.0.0`.","severity":"breaking","affected_versions":">=7.0.0"},{"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);`.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"},{"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.","message":"Core FilePond styles (`filepond.min.css`) and any plugin-specific styles must be explicitly imported into your project to ensure correct rendering.","severity":"gotcha","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Upgrade to `vue-filepond` version 5.1.3 or higher to benefit from the memory leak fix and improve application stability.","message":"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.","severity":"gotcha","affected_versions":"<5.1.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The FilePond component was not correctly registered with Vue, or the `vueFilePond` factory was not called to create the component.","error":"Failed to resolve component: file-pond or [Vue warn]: Unknown custom element: <FilePond>"},{"fix":"Plugins should be passed as arguments to the `vueFilePond` function when creating the component: `const FilePond = vueFilePond(Plugin1, Plugin2);`.","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.","error":"Cannot read properties of undefined (reading 'registerPlugin') or FilePond is not a constructor"},{"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.","cause":"The `filepond` package or its styles are not installed or correctly resolved by your bundler.","error":"Module not found: Error: Can't resolve 'filepond/dist/filepond.min.css'"},{"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.","cause":"FilePond's client-side rendering conflicts with the server-side rendered HTML, leading to hydration errors.","error":"[Vue warn]: Hydration completed but contains mismatches. (in SSR environments like Nuxt.js)"}],"ecosystem":"npm"}