or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-vue-filepond

A handy FilePond adapter component for Vue

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/vue-filepond@7.0.x

To install, run

npx @tessl/cli install tessl/npm-vue-filepond@7.0.0

index.mddocs/

Vue FilePond

Vue FilePond is a handy adapter component for FilePond, a JavaScript library that can upload anything you throw at it, optimizes images for faster uploads, and offers a great, accessible, silky smooth user experience. It provides full Vue 3 integration with reactive props, event handling, and lifecycle management.

Package Information

  • Package Name: vue-filepond
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install vue-filepond filepond

Core Imports

import vueFilePond from "vue-filepond";
import { setOptions } from "vue-filepond";

For CommonJS:

const vueFilePond = require("vue-filepond");
const { setOptions } = require("vue-filepond");

Basic Usage

// Import Vue FilePond
import vueFilePond from "vue-filepond";

// Import FilePond styles
import "filepond/dist/filepond.min.css";

// Import FilePond plugins (optional)
import FilePondPluginImagePreview from "filepond-plugin-image-preview";
import "filepond-plugin-image-preview/dist/filepond-plugin-image-preview.min.css";

// Create component with plugins
const FilePond = vueFilePond(FilePondPluginImagePreview);

export default {
  components: {
    FilePond,
  },
  data() {
    return {
      myFiles: ["photo.jpeg"],
    };
  },
  template: `
    <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"
    />
  `,
  methods: {
    handleFilePondInit() {
      console.log("FilePond has initialized");
      // FilePond instance methods are available on this.$refs.pond
    },
  },
};

Capabilities

Component Factory Function

Creates a Vue FilePond component with optional FilePond plugins.

/**
 * Creates a Vue FilePond component with optional plugins
 * @param plugins - Rest parameter accepting FilePond plugin objects
 * @returns Vue ComponentOptions object with FilePond functionality
 */
function vueFilePond(...plugins: any[]): ComponentOptions;

Usage Example:

import vueFilePond from "vue-filepond";
import FilePondPluginImagePreview from "filepond-plugin-image-preview";
import FilePondPluginFileValidateType from "filepond-plugin-file-validate-type";

// Create component with multiple plugins
const FilePond = vueFilePond(
  FilePondPluginImagePreview,
  FilePondPluginFileValidateType
);

Global Options Configuration

Sets global options for all FilePond instances.

/**
 * Sets global options for all FilePond instances
 * @param options - Object containing FilePond configuration options
 * @returns void
 */
function setOptions(options: FilePondOptionProps): void;

Usage Example:

import { setOptions } from "vue-filepond";

// Set global options that apply to all FilePond instances
setOptions({
  server: "/api/upload",
  maxFiles: 5,
  acceptedFileTypes: ["image/*"],
});

Vue Component API

The component created by the factory function provides the following interface:

Component Properties

interface VueFilePondComponent {
  name: "FilePond";
  props: VueFilepondProps;
  emits: FilePondEvents;
}

Component Props

The component accepts all FilePond option properties as Vue props. Here are the most commonly used props:

interface VueFilepondProps {
  // File handling
  allowMultiple?: boolean;
  acceptedFileTypes?: string | string[];
  files?: FilePondFile[];
  maxFiles?: number;
  maxFileSize?: string | number;
  minFileSize?: string | number;
  maxTotalFileSize?: string | number;
  
  // Server configuration  
  server?: string | FilePondServerConfig;
  
  // UI configuration
  name?: string;
  className?: string;
  labelIdle?: string;
  required?: boolean;
  disabled?: boolean;
  captureMethod?: string;
  allowDrop?: boolean;
  allowBrowse?: boolean;
  allowPaste?: boolean;
  allowReplace?: boolean;
  allowRevert?: boolean;
  allowRemove?: boolean;
  allowProcess?: boolean;
  allowReorder?: boolean;
  
  // Labels and text
  labelInvalidField?: string;
  labelFileWaitingForSize?: string;
  labelFileSizeNotAvailable?: string;
  labelFileCountSingular?: string;
  labelFileCountPlural?: string;
  labelFileLoading?: string;
  labelFileLoadError?: string;
  labelFileProcessing?: string;
  labelFileProcessingComplete?: string;
  labelFileProcessingAborted?: string;
  labelFileProcessingError?: string | ((file: FilePondFile) => string);
  labelFileProcessingRevertError?: string;
  labelFileRemoveError?: string;
  labelTapToCancel?: string;
  labelTapToRetry?: string;
  labelTapToUndo?: string;
  labelButtonRemoveItem?: string;
  labelButtonAbortItemLoad?: string;
  labelButtonRetryItemLoad?: string;
  labelButtonAbortItemProcessing?: string;
  labelButtonUndoItemProcessing?: string;
  labelButtonRetryItemProcessing?: string;
  labelButtonProcessItem?: string;
  
  // Styling and layout
  stylePanelLayout?: string;
  stylePanelAspectRatio?: string;
  styleItemPanelAspectRatio?: string;
  styleButtonRemoveItemPosition?: string;
  styleButtonProcessItemPosition?: string;
  styleLoadIndicatorPosition?: string;
  styleProgressIndicatorPosition?: string;
  
  // Drag and drop
  dropOnPage?: boolean;
  dropOnElement?: boolean;
  dropValidation?: boolean;
  
  // File validation (requires plugins)
  fileValidateTypeDetectType?: (source: any, type: string) => Promise<string>;
  fileValidateTypeLabelExpectedTypes?: string;
  fileValidateTypeLabelExpectedTypesMap?: { [key: string]: string };
  allowFileTypeValidation?: boolean;
  
  // Size validation
  allowFileSizeValidation?: boolean;
  fileValidateSizeLabelFormatError?: string;
  fileValidateSizeLabelImageSizeTooSmall?: string;
  fileValidateSizeLabelImageSizeTooBig?: string;
  fileValidateSizeLabelExpectedMinSize?: string;
  fileValidateSizeLabelExpectedMaxSize?: string;
  
  // Image processing (requires plugins)
  allowImagePreview?: boolean;
  imagePreviewHeight?: number;
  imagePreviewMinHeight?: number;
  imagePreviewMaxHeight?: number;
  imagePreviewMaxFileSize?: string;
  imagePreviewZoomFactor?: number;
  imagePreviewUpscale?: boolean;
  imagePreviewTransparencyIndicator?: string;
  
  // Image editing (requires plugins)
  allowImageEdit?: boolean;
  imageEditInstantEdit?: boolean;
  imageEditAllowEdit?: boolean;
  imageEditIconEdit?: string;
  
  // Image resizing (requires plugins)
  allowImageResize?: boolean;
  imageResizeTargetWidth?: number;
  imageResizeTargetHeight?: number;
  imageResizeMode?: string;
  imageResizeUpscale?: boolean;
  
  // Image cropping (requires plugins)
  allowImageCrop?: boolean;
  imageCropAspectRatio?: number;
  
  // Image transforming (requires plugins)
  allowImageTransform?: boolean;
  imageTransformOutputMimeType?: string;
  imageTransformOutputQuality?: number;
  imageTransformOutputStripImageHead?: boolean;
  imageTransformClientTransforms?: string[];
  imageTransformCanvasMemoryLimit?: number;
  
  // File metadata (requires plugins)
  allowFileMetadata?: boolean;
  fileMetadataObject?: any;
}

Component Events

All FilePond callback events are available as Vue events (with 'on' prefix removed):

interface FilePondEvents {
  // Lifecycle events
  init: () => void;
  warning: (error: any, file?: FilePondFile, status?: any) => void;
  error: (error: any, file?: FilePondFile, status?: any) => void;
  
  // File lifecycle events
  addfile: (error: any, file: FilePondFile) => void;
  removefile: (error: any, file: FilePondFile) => void;
  preparefile: (file: FilePondFile, output: any) => void;
  addfilestart: (file: FilePondFile) => void;
  addfileprogress: (file: FilePondFile, progress: number) => void;
  addfileprocess: (file: FilePondFile) => void;
  
  // File processing events
  processfile: (error: any, file: FilePondFile) => void;
  processfilestart: (file: FilePondFile) => void;
  processfileprogress: (file: FilePondFile, progress: number) => void;
  processfileabort: (file: FilePondFile) => void;
  processfilerevert: (file: FilePondFile) => void;
  processfiles: () => void;
  
  // File interaction events
  activatefile: (file: FilePondFile) => void;
  reorderfiles: (files: FilePondFile[], origin: any, target: any) => void;
  updatefiles: (files: FilePondFile[]) => void;
  
  // Special Vue event for v-model support
  input: (files: FilePondFile[]) => void;
}

Component Methods

The component exposes FilePond instance methods via template refs:

interface VueFilePondInstanceMethods {
  // File management
  addFile(source: any, options?: any): Promise<FilePondFile>;
  addFiles(sources: any[], options?: any): Promise<FilePondFile[]>;
  removeFile(query: string | number | FilePondFile): boolean;
  removeFiles(options?: any): void;
  moveFile(query: string | number | FilePondFile, index: number): boolean;
  
  // File retrieval
  getFile(query: string | number): FilePondFile | null;
  getFiles(): FilePondFile[];
  
  // File processing
  prepareFile(query: string | number | FilePondFile): Promise<FilePondFile>;
  prepareFiles(queries?: any[]): Promise<FilePondFile[]>;
  processFile(query: string | number | FilePondFile): Promise<FilePondFile>;
  processFiles(queries?: any[]): Promise<FilePondFile[]>;
  
  // File state management
  removeFileFromProcessQueue(query: string | number | FilePondFile): void;
  removeFileFromPrepareQueue(query: string | number | FilePondFile): void;
  
  // UI interactions
  browse(): void;
  sort(compare?: (a: FilePondFile, b: FilePondFile) => number): void;
  
  // Status and properties
  disabled: boolean;
  required: boolean;
  element: HTMLElement;
  
  // Instance information
  pond: any; // Internal FilePond instance
}

Usage Example:

// In Vue component
export default {
  methods: {
    addFileToFilePond() {
      this.$refs.pond.addFile("path/to/file.jpg");
    },
    getAllFiles() {
      const files = this.$refs.pond.getFiles();
      console.log("Current files:", files);
    },
    processAllFiles() {
      this.$refs.pond.processFiles();
    },
  },
  template: `
    <file-pond 
      ref="pond"
      @init="handleInit"
      @addfile="handleAddFile"
    />
  `,
};

Types

FilePond Types

interface FilePondFile {
  id: string;
  serverId: string | null;
  status: number;
  filename: string;
  filenameWithoutExtension: string;
  fileExtension: string;
  fileType: string;
  fileSize: number;
  file: File;
  source: any;
  getMetadata(key?: string): any;
  setMetadata(key: string, value: any): void;
}

interface FilePondServerConfig {
  url?: string;
  timeout?: number;
  process?: string | FilePondServerConfigProcess;
  revert?: string | FilePondServerConfigRevert;
  restore?: string | FilePondServerConfigRestore;
  load?: string | FilePondServerConfigLoad;
  fetch?: string | FilePondServerConfigFetch;
}

interface FilePondServerConfigProcess {
  url: string;
  method?: string;
  headers?: { [key: string]: string };
  withCredentials?: boolean;
  timeout?: number;
  onload?: (response: any) => any;
  onerror?: (response: any) => any;
  ondata?: (formData: FormData) => FormData;
}

interface FilePondServerConfigRevert {
  url: string;
  method?: string;
  headers?: { [key: string]: string };
  withCredentials?: boolean;
  timeout?: number;
  onload?: (response: any) => any;
  onerror?: (response: any) => any;
}

interface FilePondServerConfigRestore {
  url: string;
  method?: string;
  headers?: { [key: string]: string };
  withCredentials?: boolean;
  timeout?: number;
  onload?: (response: any) => any;
  onerror?: (response: any) => any;
}

interface FilePondServerConfigLoad {
  url: string;
  method?: string;
  headers?: { [key: string]: string };
  withCredentials?: boolean;
  timeout?: number;
  onload?: (response: any) => any;
  onerror?: (response: any) => any;
}

interface FilePondServerConfigFetch {
  url: string;
  method?: string;
  headers?: { [key: string]: string };
  withCredentials?: boolean;
  timeout?: number;
  onload?: (response: any) => any;
  onerror?: (response: any) => any;
}

Vue FilePond Specific Types

// Utility type for excluding properties
type Except<ObjectType, KeysType extends keyof ObjectType> = Pick<ObjectType, Exclude<keyof ObjectType, KeysType>>;

// FilePond base types (from filepond package)
interface FilePondOptionProps {
  allowMultiple?: boolean;
  acceptedFileTypes?: string | string[];
  files?: FilePondFile[];
  server?: string | FilePondServerConfig;
  // ... all other FilePond options
}

interface FilePondCallbackProps {
  oninit?: () => void;
  onaddfile?: (error: any, file: FilePondFile) => void;
  onprocessfile?: (error: any, file: FilePondFile) => void;
  // ... all other FilePond callback properties
}

interface FilePond {
  // All FilePond instance methods and properties
  addFile(source: any, options?: any): Promise<FilePondFile>;
  removeFile(query: any): boolean;
  getFiles(): FilePondFile[];
  // ... all other FilePond methods
  setOptions(options: any): void;
  on(event: string, callback: Function): void;
  off(event: string, callback?: Function): void;
  destroy(): void;
  // ... other internal methods
}

// Vue FilePond component types
interface VueFilePondComponent extends VueConstructor<VueFilePondInstanceMethods> {}

type VueFilepondProps = Except<FilePondOptionProps, keyof FilePondCallbackProps>;

type VueFilePondInstanceMethods = Except<FilePond, FilteredMethods>;

type FilteredMethods = 
  | 'setOptions'
  | 'on' 
  | 'off'
  | 'onOnce'
  | 'appendTo'
  | 'insertAfter'
  | 'insertBefore'
  | 'isAttachedTo'
  | 'replaceElement'
  | 'restoreElement'
  | 'destroy';

Browser Support

Vue FilePond requires:

  • Vue 3.x (peer dependency)
  • FilePond 4.7.4 or higher (peer dependency)
  • Modern browser with FilePond support

The component automatically detects browser support and will not initialize FilePond if the browser is not supported.

SSR Support

When using Vue FilePond with server-side rendering (like Nuxt.js), wrap the component in a client-only wrapper:

<template>
  <ClientOnly>
    <file-pond />
  </ClientOnly>
</template>

Or for Nuxt.js 2:

<template>
  <no-ssr>
    <file-pond />
  </no-ssr>
</template>

Additional Features

Browser Support Detection

FilePond includes built-in browser support detection:

/**
 * Check if FilePond is supported in the current browser (from filepond package)
 * @returns boolean indicating browser support
 */
const supported: () => boolean;

Usage Example:

import { supported } from "filepond";

if (supported()) {
  // FilePond is supported, safe to initialize
  const FilePond = vueFilePond();
} else {
  // Provide fallback UI for unsupported browsers
  console.warn("FilePond is not supported in this browser");
}