0
# Vue FilePond
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: vue-filepond
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install vue-filepond filepond`
10

11
## Core Imports
12

13
```javascript
14
import vueFilePond from "vue-filepond";
15
import { setOptions } from "vue-filepond";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const vueFilePond = require("vue-filepond");
22
const { setOptions } = require("vue-filepond");
23
```
24

25
## Basic Usage
26

27
```javascript
28
// Import Vue FilePond
29
import vueFilePond from "vue-filepond";
30

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

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

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

41
export default {
42
  components: {
43
    FilePond,
44
  },
45
  data() {
46
    return {
47
      myFiles: ["photo.jpeg"],
48
    };
49
  },
50
  template: `
51
    <file-pond
52
      name="test"
53
      ref="pond"
54
      label-idle="Drop files here..."
55
      v-bind:allow-multiple="true"  
56
      accepted-file-types="image/jpeg, image/png"
57
      server="/api"
58
      v-bind:files="myFiles"
59
      v-on:init="handleFilePondInit"
60
    />
61
  `,
62
  methods: {
63
    handleFilePondInit() {
64
      console.log("FilePond has initialized");
65
      // FilePond instance methods are available on this.$refs.pond
66
    },
67
  },
68
};
69
```
70

71
## Capabilities
72

73
### Component Factory Function
74

75
Creates a Vue FilePond component with optional FilePond plugins.
76

77
```javascript { .api }
78
/**
79
 * Creates a Vue FilePond component with optional plugins
80
 * @param plugins - Rest parameter accepting FilePond plugin objects
81
 * @returns Vue ComponentOptions object with FilePond functionality
82
 */
83
function vueFilePond(...plugins: any[]): ComponentOptions;
84
```
85

86
**Usage Example:**
87

88
```javascript
89
import vueFilePond from "vue-filepond";
90
import FilePondPluginImagePreview from "filepond-plugin-image-preview";
91
import FilePondPluginFileValidateType from "filepond-plugin-file-validate-type";
92

93
// Create component with multiple plugins
94
const FilePond = vueFilePond(
95
  FilePondPluginImagePreview,
96
  FilePondPluginFileValidateType
97
);
98
```
99

100
### Global Options Configuration
101

102
Sets global options for all FilePond instances.
103

104
```javascript { .api }
105
/**
106
 * Sets global options for all FilePond instances
107
 * @param options - Object containing FilePond configuration options
108
 * @returns void
109
 */
110
function setOptions(options: FilePondOptionProps): void;
111
```
112

113
**Usage Example:**
114

115
```javascript
116
import { setOptions } from "vue-filepond";
117

118
// Set global options that apply to all FilePond instances
119
setOptions({
120
  server: "/api/upload",
121
  maxFiles: 5,
122
  acceptedFileTypes: ["image/*"],
123
});
124
```
125

126
## Vue Component API
127

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

130
### Component Properties
131

132
```javascript { .api }
133
interface VueFilePondComponent {
134
  name: "FilePond";
135
  props: VueFilepondProps;
136
  emits: FilePondEvents;
137
}
138
```
139

140
### Component Props
141

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

144
```javascript { .api }
145
interface VueFilepondProps {
146
  // File handling
147
  allowMultiple?: boolean;
148
  acceptedFileTypes?: string | string[];
149
  files?: FilePondFile[];
150
  maxFiles?: number;
151
  maxFileSize?: string | number;
152
  minFileSize?: string | number;
153
  maxTotalFileSize?: string | number;
154
  
155
  // Server configuration  
156
  server?: string | FilePondServerConfig;
157
  
158
  // UI configuration
159
  name?: string;
160
  className?: string;
161
  labelIdle?: string;
162
  required?: boolean;
163
  disabled?: boolean;
164
  captureMethod?: string;
165
  allowDrop?: boolean;
166
  allowBrowse?: boolean;
167
  allowPaste?: boolean;
168
  allowReplace?: boolean;
169
  allowRevert?: boolean;
170
  allowRemove?: boolean;
171
  allowProcess?: boolean;
172
  allowReorder?: boolean;
173
  
174
  // Labels and text
175
  labelInvalidField?: string;
176
  labelFileWaitingForSize?: string;
177
  labelFileSizeNotAvailable?: string;
178
  labelFileCountSingular?: string;
179
  labelFileCountPlural?: string;
180
  labelFileLoading?: string;
181
  labelFileLoadError?: string;
182
  labelFileProcessing?: string;
183
  labelFileProcessingComplete?: string;
184
  labelFileProcessingAborted?: string;
185
  labelFileProcessingError?: string | ((file: FilePondFile) => string);
186
  labelFileProcessingRevertError?: string;
187
  labelFileRemoveError?: string;
188
  labelTapToCancel?: string;
189
  labelTapToRetry?: string;
190
  labelTapToUndo?: string;
191
  labelButtonRemoveItem?: string;
192
  labelButtonAbortItemLoad?: string;
193
  labelButtonRetryItemLoad?: string;
194
  labelButtonAbortItemProcessing?: string;
195
  labelButtonUndoItemProcessing?: string;
196
  labelButtonRetryItemProcessing?: string;
197
  labelButtonProcessItem?: string;
198
  
199
  // Styling and layout
200
  stylePanelLayout?: string;
201
  stylePanelAspectRatio?: string;
202
  styleItemPanelAspectRatio?: string;
203
  styleButtonRemoveItemPosition?: string;
204
  styleButtonProcessItemPosition?: string;
205
  styleLoadIndicatorPosition?: string;
206
  styleProgressIndicatorPosition?: string;
207
  
208
  // Drag and drop
209
  dropOnPage?: boolean;
210
  dropOnElement?: boolean;
211
  dropValidation?: boolean;
212
  
213
  // File validation (requires plugins)
214
  fileValidateTypeDetectType?: (source: any, type: string) => Promise<string>;
215
  fileValidateTypeLabelExpectedTypes?: string;
216
  fileValidateTypeLabelExpectedTypesMap?: { [key: string]: string };
217
  allowFileTypeValidation?: boolean;
218
  
219
  // Size validation
220
  allowFileSizeValidation?: boolean;
221
  fileValidateSizeLabelFormatError?: string;
222
  fileValidateSizeLabelImageSizeTooSmall?: string;
223
  fileValidateSizeLabelImageSizeTooBig?: string;
224
  fileValidateSizeLabelExpectedMinSize?: string;
225
  fileValidateSizeLabelExpectedMaxSize?: string;
226
  
227
  // Image processing (requires plugins)
228
  allowImagePreview?: boolean;
229
  imagePreviewHeight?: number;
230
  imagePreviewMinHeight?: number;
231
  imagePreviewMaxHeight?: number;
232
  imagePreviewMaxFileSize?: string;
233
  imagePreviewZoomFactor?: number;
234
  imagePreviewUpscale?: boolean;
235
  imagePreviewTransparencyIndicator?: string;
236
  
237
  // Image editing (requires plugins)
238
  allowImageEdit?: boolean;
239
  imageEditInstantEdit?: boolean;
240
  imageEditAllowEdit?: boolean;
241
  imageEditIconEdit?: string;
242
  
243
  // Image resizing (requires plugins)
244
  allowImageResize?: boolean;
245
  imageResizeTargetWidth?: number;
246
  imageResizeTargetHeight?: number;
247
  imageResizeMode?: string;
248
  imageResizeUpscale?: boolean;
249
  
250
  // Image cropping (requires plugins)
251
  allowImageCrop?: boolean;
252
  imageCropAspectRatio?: number;
253
  
254
  // Image transforming (requires plugins)
255
  allowImageTransform?: boolean;
256
  imageTransformOutputMimeType?: string;
257
  imageTransformOutputQuality?: number;
258
  imageTransformOutputStripImageHead?: boolean;
259
  imageTransformClientTransforms?: string[];
260
  imageTransformCanvasMemoryLimit?: number;
261
  
262
  // File metadata (requires plugins)
263
  allowFileMetadata?: boolean;
264
  fileMetadataObject?: any;
265
}
266
```
267

268
### Component Events
269

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

272
```javascript { .api }
273
interface FilePondEvents {
274
  // Lifecycle events
275
  init: () => void;
276
  warning: (error: any, file?: FilePondFile, status?: any) => void;
277
  error: (error: any, file?: FilePondFile, status?: any) => void;
278
  
279
  // File lifecycle events
280
  addfile: (error: any, file: FilePondFile) => void;
281
  removefile: (error: any, file: FilePondFile) => void;
282
  preparefile: (file: FilePondFile, output: any) => void;
283
  addfilestart: (file: FilePondFile) => void;
284
  addfileprogress: (file: FilePondFile, progress: number) => void;
285
  addfileprocess: (file: FilePondFile) => void;
286
  
287
  // File processing events
288
  processfile: (error: any, file: FilePondFile) => void;
289
  processfilestart: (file: FilePondFile) => void;
290
  processfileprogress: (file: FilePondFile, progress: number) => void;
291
  processfileabort: (file: FilePondFile) => void;
292
  processfilerevert: (file: FilePondFile) => void;
293
  processfiles: () => void;
294
  
295
  // File interaction events
296
  activatefile: (file: FilePondFile) => void;
297
  reorderfiles: (files: FilePondFile[], origin: any, target: any) => void;
298
  updatefiles: (files: FilePondFile[]) => void;
299
  
300
  // Special Vue event for v-model support
301
  input: (files: FilePondFile[]) => void;
302
}
303
```
304

305
### Component Methods
306

307
The component exposes FilePond instance methods via template refs:
308

309
```javascript { .api }
310
interface VueFilePondInstanceMethods {
311
  // File management
312
  addFile(source: any, options?: any): Promise<FilePondFile>;
313
  addFiles(sources: any[], options?: any): Promise<FilePondFile[]>;
314
  removeFile(query: string | number | FilePondFile): boolean;
315
  removeFiles(options?: any): void;
316
  moveFile(query: string | number | FilePondFile, index: number): boolean;
317
  
318
  // File retrieval
319
  getFile(query: string | number): FilePondFile | null;
320
  getFiles(): FilePondFile[];
321
  
322
  // File processing
323
  prepareFile(query: string | number | FilePondFile): Promise<FilePondFile>;
324
  prepareFiles(queries?: any[]): Promise<FilePondFile[]>;
325
  processFile(query: string | number | FilePondFile): Promise<FilePondFile>;
326
  processFiles(queries?: any[]): Promise<FilePondFile[]>;
327
  
328
  // File state management
329
  removeFileFromProcessQueue(query: string | number | FilePondFile): void;
330
  removeFileFromPrepareQueue(query: string | number | FilePondFile): void;
331
  
332
  // UI interactions
333
  browse(): void;
334
  sort(compare?: (a: FilePondFile, b: FilePondFile) => number): void;
335
  
336
  // Status and properties
337
  disabled: boolean;
338
  required: boolean;
339
  element: HTMLElement;
340
  
341
  // Instance information
342
  pond: any; // Internal FilePond instance
343
}
344
```
345

346
**Usage Example:**
347

348
```javascript
349
// In Vue component
350
export default {
351
  methods: {
352
    addFileToFilePond() {
353
      this.$refs.pond.addFile("path/to/file.jpg");
354
    },
355
    getAllFiles() {
356
      const files = this.$refs.pond.getFiles();
357
      console.log("Current files:", files);
358
    },
359
    processAllFiles() {
360
      this.$refs.pond.processFiles();
361
    },
362
  },
363
  template: `
364
    <file-pond 
365
      ref="pond"
366
      @init="handleInit"
367
      @addfile="handleAddFile"
368
    />
369
  `,
370
};
371
```
372

373
## Types
374

375
### FilePond Types
376

377
```javascript { .api }
378
interface FilePondFile {
379
  id: string;
380
  serverId: string | null;
381
  status: number;
382
  filename: string;
383
  filenameWithoutExtension: string;
384
  fileExtension: string;
385
  fileType: string;
386
  fileSize: number;
387
  file: File;
388
  source: any;
389
  getMetadata(key?: string): any;
390
  setMetadata(key: string, value: any): void;
391
}
392

393
interface FilePondServerConfig {
394
  url?: string;
395
  timeout?: number;
396
  process?: string | FilePondServerConfigProcess;
397
  revert?: string | FilePondServerConfigRevert;
398
  restore?: string | FilePondServerConfigRestore;
399
  load?: string | FilePondServerConfigLoad;
400
  fetch?: string | FilePondServerConfigFetch;
401
}
402

403
interface FilePondServerConfigProcess {
404
  url: string;
405
  method?: string;
406
  headers?: { [key: string]: string };
407
  withCredentials?: boolean;
408
  timeout?: number;
409
  onload?: (response: any) => any;
410
  onerror?: (response: any) => any;
411
  ondata?: (formData: FormData) => FormData;
412
}
413

414
interface FilePondServerConfigRevert {
415
  url: string;
416
  method?: string;
417
  headers?: { [key: string]: string };
418
  withCredentials?: boolean;
419
  timeout?: number;
420
  onload?: (response: any) => any;
421
  onerror?: (response: any) => any;
422
}
423

424
interface FilePondServerConfigRestore {
425
  url: string;
426
  method?: string;
427
  headers?: { [key: string]: string };
428
  withCredentials?: boolean;
429
  timeout?: number;
430
  onload?: (response: any) => any;
431
  onerror?: (response: any) => any;
432
}
433

434
interface FilePondServerConfigLoad {
435
  url: string;
436
  method?: string;
437
  headers?: { [key: string]: string };
438
  withCredentials?: boolean;
439
  timeout?: number;
440
  onload?: (response: any) => any;
441
  onerror?: (response: any) => any;
442
}
443

444
interface FilePondServerConfigFetch {
445
  url: string;
446
  method?: string;
447
  headers?: { [key: string]: string };
448
  withCredentials?: boolean;
449
  timeout?: number;
450
  onload?: (response: any) => any;
451
  onerror?: (response: any) => any;
452
}
453
```
454

455
### Vue FilePond Specific Types
456

457
```javascript { .api }
458
// Utility type for excluding properties
459
type Except<ObjectType, KeysType extends keyof ObjectType> = Pick<ObjectType, Exclude<keyof ObjectType, KeysType>>;
460

461
// FilePond base types (from filepond package)
462
interface FilePondOptionProps {
463
  allowMultiple?: boolean;
464
  acceptedFileTypes?: string | string[];
465
  files?: FilePondFile[];
466
  server?: string | FilePondServerConfig;
467
  // ... all other FilePond options
468
}
469

470
interface FilePondCallbackProps {
471
  oninit?: () => void;
472
  onaddfile?: (error: any, file: FilePondFile) => void;
473
  onprocessfile?: (error: any, file: FilePondFile) => void;
474
  // ... all other FilePond callback properties
475
}
476

477
interface FilePond {
478
  // All FilePond instance methods and properties
479
  addFile(source: any, options?: any): Promise<FilePondFile>;
480
  removeFile(query: any): boolean;
481
  getFiles(): FilePondFile[];
482
  // ... all other FilePond methods
483
  setOptions(options: any): void;
484
  on(event: string, callback: Function): void;
485
  off(event: string, callback?: Function): void;
486
  destroy(): void;
487
  // ... other internal methods
488
}
489

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

493
type VueFilepondProps = Except<FilePondOptionProps, keyof FilePondCallbackProps>;
494

495
type VueFilePondInstanceMethods = Except<FilePond, FilteredMethods>;
496

497
type FilteredMethods = 
498
  | 'setOptions'
499
  | 'on' 
500
  | 'off'
501
  | 'onOnce'
502
  | 'appendTo'
503
  | 'insertAfter'
504
  | 'insertBefore'
505
  | 'isAttachedTo'
506
  | 'replaceElement'
507
  | 'restoreElement'
508
  | 'destroy';
509
```
510

511
## Browser Support
512

513
Vue FilePond requires:
514
- Vue 3.x (peer dependency)
515
- FilePond 4.7.4 or higher (peer dependency)
516
- Modern browser with FilePond support
517

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

520
## SSR Support
521

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

524
```vue
525
<template>
526
  <ClientOnly>
527
    <file-pond />
528
  </ClientOnly>
529
</template>
530
```
531

532
Or for Nuxt.js 2:
533

534
```vue
535
<template>
536
  <no-ssr>
537
    <file-pond />
538
  </no-ssr>
539
</template>
540
```
541

542
## Additional Features
543

544
### Browser Support Detection
545

546
FilePond includes built-in browser support detection:
547

548
```javascript { .api }
549
/**
550
 * Check if FilePond is supported in the current browser (from filepond package)
551
 * @returns boolean indicating browser support
552
 */
553
const supported: () => boolean;
554
```
555

556
**Usage Example:**
557

558
```javascript
559
import { supported } from "filepond";
560

561
if (supported()) {
562
  // FilePond is supported, safe to initialize
563
  const FilePond = vueFilePond();
564
} else {
565
  // Provide fallback UI for unsupported browsers
566
  console.warn("FilePond is not supported in this browser");
567
}
568
```
569