FilePond Adapter for React

Common errors

• TypeError: registerPlugin is not a function

  cause Attempting to call `registerPlugin` without importing it as a named export, or using a CommonJS `require` that doesn't correctly destructure the export.
  fix Ensure you are using `import { registerPlugin } from 'react-filepond';` for ESM environments, or access it via `require('react-filepond').registerPlugin` for CommonJS.

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

  cause The `filepond` package or its styles are not correctly installed or the import path is wrong.
  fix Verify `filepond` is installed via `npm install filepond` and the import path `filepond/dist/filepond.min.css` is correct and accessible.

• Property 'files' does not exist on type 'IntrinsicAttributes & FilePondProps'. Did you mean 'file'?

  cause This TypeScript error indicates a type mismatch, often because `@types/react-filepond` is still installed alongside the new built-in types from `react-filepond` v7.1.0+.
  fix Remove the `@types/react-filepond` package from your project as `react-filepond` now ships its own types (`npm uninstall @types/react-filepond`).

Warnings

• breaking As of version 7.1.0, `react-filepond` ships its own TypeScript types. The separate `@types/react-filepond` package is no longer needed and should be uninstalled.
  Fix: Uninstall the `@types/react-filepond` package: `npm uninstall @types/react-filepond` or `yarn remove @types/react-filepond`.
• gotcha FilePond plugins (e.g., Image Preview, EXIF Orientation) and their associated styles must be installed and imported separately from `react-filepond` and `filepond` itself. Failing to install/import them will result in missing functionality or broken styling.
  Fix: Ensure all required plugins are installed (`npm i filepond-plugin-image-preview filepond-plugin-image-exif-orientation`) and their styles imported (`import 'filepond-plugin-image-preview/dist/filepond-plugin-image-preview.css';`) in addition to `filepond.min.css`.
• gotcha The `filepond` core library and `react-filepond` have peer dependencies on `react` and `react-dom` within specific version ranges. Mismatched React versions can lead to rendering issues or crashes.
  Fix: Ensure your project's `react` and `react-dom` versions (16-19 for `react-filepond` v7) satisfy the peer dependency requirements of both `filepond` and `react-filepond`.

Install

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

Imports

• FilePond
  wrong:

  const FilePond = require('react-filepond').FilePond;

  correct:

  import { FilePond } from 'react-filepond';

  Primary component for rendering the FilePond instance. Named import is standard.
• registerPlugin
  wrong:

  import registerPlugin from 'react-filepond/registerPlugin';

  correct:

  import { registerPlugin } from 'react-filepond';

  Function to register FilePond plugins globally. Available as a named export from the main package.
• FilePond styles

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

  Required to style the FilePond component. Import directly from the `filepond` package, not `react-filepond`.
• Plugin styles

  import 'filepond-plugin-image-preview/dist/filepond-plugin-image-preview.css';

  Many FilePond plugins have their own CSS that needs to be imported separately after installation.

Quickstart

Demonstrates a basic FilePond setup in a React functional component, including state management for files, registering common plugins (Image EXIF Orientation, Image Preview), and configuring a server endpoint for uploads.

import React, { useState } from 'react';
import ReactDOM from 'react-dom/client';
import { FilePond, registerPlugin } from 'react-filepond';
import 'filepond/dist/filepond.min.css';
import FilePondPluginImageExifOrientation from 'filepond-plugin-image-exif-orientation';
import FilePondPluginImagePreview from 'filepond-plugin-image-preview';
import 'filepond-plugin-image-preview/dist/filepond-plugin-image-preview.css';

// Register the plugins (ensure they are installed via npm)
registerPlugin(FilePondPluginImageExifOrientation, FilePondPluginImagePreview);

function App() {
  const [files, setFiles] = useState([]);

  // Example of a dummy server endpoint for demonstration. 
  // In a real app, this would point to your backend upload API.
  const serverEndpoint = process.env.REACT_APP_UPLOAD_API || '/api/upload'; 

  return (
    <div className="App" style={{ maxWidth: '500px', margin: '50px auto' }}>
      <h1>Upload Files</h1>
      <FilePond
        files={files}
        onupdatefiles={setFiles}
        allowMultiple={true}
        maxFiles={3}
        server={serverEndpoint}
        name="files" 
        labelIdle='Drag & Drop your files or <span class="filepond--label-action">Browse</span>'
      />
      {files.length > 0 && (
        <div style={{ marginTop: '20px' }}>
          <h3>Current Files:</h3>
          <ul>
            {files.map((fileItem, index) => (
              <li key={index}>{fileItem.file.name}</li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);