Filepicker.js Client Library

2.4.18 · deprecated · verified Sun Apr 19

The `filepicker-js` package is the JavaScript client library for the original Filepicker.io service, which was acquired and rebranded as Filestack in 2015. The library's latest version, 2.4.18, was published over 10 years ago, indicating it is no longer actively maintained under this name. Modern development and new features are now exclusively available through the `filestack-js` SDK. This library primarily provides methods for file picking, storing, reading, writing, and basic image transformations, facilitating direct integration of file upload capabilities from various sources into web applications. It supports traditional browser script tag inclusion, exposing `window.filepicker`, and CommonJS `require()` for compatibility with older bundlers like Browserify. Its primary differentiator was simplifying file ingestion from diverse sources into web applications.

Common errors

```
ReferenceError: filepicker is not defined
```
cause The `filepicker.js` script was not loaded successfully via a `<script>` tag, or the global `filepicker` object was accessed before the script completed execution.

fix Ensure the `<script src="//api.filepicker.io/v2/filepicker.js"></script>` tag is correctly placed in your HTML, preferably in the `<head>` or before your application code, and that there are no network issues preventing its load. For non-blocking loading, use the provided asynchronous script snippet.
```
TypeError: filepicker.setKey is not a function
```
cause The `filepicker` object exists but is not fully initialized, or its methods are not yet available. This often happens if `filepicker.js` is still loading asynchronously or if the API key is not being set correctly after initialization.

fix Verify that `filepicker.js` has completely loaded and the `filepicker` global is fully populated before calling `setKey`. If loading asynchronously, place `setKey` within a callback or after an event that signifies library readiness.
```
Cannot find module 'filepicker-js'
```
cause When using `require('filepicker-js')` in a CommonJS environment, this error indicates that the `filepicker-js` package was not installed or your bundler (e.g., Browserify) failed to resolve it.

fix Run `npm install filepicker-js --save` to ensure the package is installed. If using a bundler, confirm its configuration correctly handles CommonJS modules and that the package is included in the build process.

Warnings

breaking The `filepicker-js` package is deprecated. The underlying service, Filepicker.io, was rebranded to Filestack in 2015. Active development, maintenance, and new features are now exclusively available through the `filestack-js` SDK. Users should plan to migrate to `filestack-js` for continued support and access to modern capabilities.
Fix: Migrate your integration to the `filestack-js` library (available via `npm install filestack-js`) and update your API key and usage patterns according to Filestack's current documentation.
gotcha The library primarily relies on exposing `filepicker` as a global variable when loaded via a `<script>` tag or expects a CommonJS `require()` pattern. It does not natively support modern ES Module (`import/export`) syntax, which can lead to integration challenges in contemporary JavaScript projects.
Fix: When using in modern environments, ensure proper bundling (e.g., Webpack or Rollup with CJS plugins) or consider using `filestack-js` which offers better ES Module support. If using `<script>` tags, ensure the `filepicker.js` script loads before attempting to access `window.filepicker`.
deprecated The README mentions Bower as an installation method for `filepicker-js`. Bower is a deprecated package manager and should not be used for new projects or ongoing maintenance.
Fix: Avoid using Bower. If you must use this deprecated library, rely on npm (`npm install filepicker-js`) for package management in conjunction with a CommonJS-aware bundler like Browserify, or directly include the script via a `<script>` tag.

Install

npm install filepicker-js npm
yarn add filepicker-js yarn
pnpm add filepicker-js pnpm

Imports

filepicker

wrong:

import filepicker from 'filepicker-js';

correct:

<!-- In HTML -->
<script type="text/javascript" src="//api.filepicker.io/v2/filepicker.js"></script>
<script type="text/javascript">
  // 'filepicker' is now a global object
  filepicker.setKey('YOUR_API_KEY');
</script>

The library primarily exposes 'filepicker' as a global object when loaded via a script tag. It does not provide ES Module exports. This global object contains all public methods.

filepicker
wrong:
```
import * as filepicker from 'filepicker-js';
```
correct:
```
const filepicker = require('filepicker-js');
```
For environments using CommonJS (e.g., Node.js or older bundlers like Browserify), the library can be imported using 'require()'. It does not support ES Module `import` syntax.
pick
wrong:
```
filepicker.pick(...); // Without explicit window. or require()
```
correct:
```
window.filepicker.pick(...); // After script tag load
// OR
const filepicker = require('filepicker-js'); filepicker.pick(...); // With CommonJS
```
The `pick` method, along with others like `setKey`, `pickMultiple`, `store`, etc., are accessed directly from the `filepicker` object, whether it's the global `window.filepicker` or the CommonJS import.

Quickstart

This quickstart demonstrates how to integrate `filepicker-js` into an HTML page, set the API key, and initiate a file selection and upload process using the `pick` method, displaying the uploaded file's URL.

<html>
<head>
  <title>Filepicker.js Quickstart</title>
</head>
<body>
  <h1>Upload a File with Filepicker.js</h1>
  <button id="upload-button">Pick File</button>

  <script type="text/javascript" src="//api.filepicker.io/v2/filepicker.js"></script>
  <script type="text/javascript">
    // Replace with your actual API key from Filepicker.io (or Filestack)
    const API_KEY = process.env.FILEPICKER_API_KEY ?? 'YOUR_FILEPICKER_API_KEY';

    (function(){
      if(!window.filepicker) {
        console.error('Filepicker.js failed to load.');
        return;
      }

      filepicker.setKey(API_KEY);

      document.getElementById('upload-button').addEventListener('click', function() {
        filepicker.pick({
          mimetype: 'image/*',
          container: 'window',
          services: ['COMPUTER', 'DROPBOX', 'GOOGLE_DRIVE', 'FACEBOOK']
        }, function(Blob){
          console.log('Upload successful! File details:', JSON.stringify(Blob));
          alert('File uploaded: ' + Blob.url);
        }, function(FPError){
          console.error('Upload failed:', FPError.toString());
          alert('File upload failed: ' + FPError.toString());
        });
      });

      console.log('Filepicker.js initialized. Click the button to pick a file.');
    })();
  </script>
</body>
</html>

view raw JSON →