Filestack for React ⚛️

The filestack-react library is a component-based wrapper for the core filestack-js SDK. It’s designed to help you integrate Filestack’s file handling services into your React applications with minimal effort and a familiar developer experience. You can implement the powerful Filestack Picker and its features in just a few lines of code.

Compatibility Notice: The filestack-react library currently supports React versions 18.3+ and 19. Node (to build/develop): >=18. If you are starting a new project, please ensure you are using a compatible version of React.

npm install filestack-react filestack-js

import { PickerOverlay } from 'filestack-react';

const App = () => (
  <PickerOverlay
    apikey={'YOUR_API_KEY'}
    onUploadDone={(res) => console.log(res)}
  />
);

import { PickerOverlay } from 'filestack-react';

<PickerOverlay apikey={'YOUR_APIKEY'} />

import { PickerInline } from 'filestack-react';

<PickerInline apikey={'YOUR_APIKEY'} />

import { PickerDropPane } from 'filestack-react';

<PickerDropPane apikey={'YOUR_APIKEY'} />

To embed the PickerInline or PickerDropPane in a specific element, pass that element as a child.

<PickerInline apikey={'YOUR_APIKEY'}>
  <div id="my-filestack-container" style={{ height: '400px' }} />
</PickerInline>

For advanced use cases, you can access the underlying filestack-js client instance directly. This allows you to use methods like transform(), storeURL(), and remove().

import { client } from 'filestack-react';

const filestackClient = client.init('YOUR_APIKEY');

filestackClient.transform(handle, { resize: { width: 100 } })
  .then(res => {
    console.log(res);
  });

Introduced in v7, the FilestackProvider context lets users save time by automatically syncing the same configuration across their picker components.

Previously, rendering several pickers in the same app required that every picker component have its own apikey, clientOptions, and callback props. Even when the pickers had identical configurations. Starting in version 7.0.0, users can use the FilestackProvider to wrap an app (or any subtree) and hold the configuration in context. Meaning that any picker components underneath it automatically read from the provider, and only fallback to their own prop if explicitly indicated.

This is a useful tool for those users who have apps that render the picker in multiple places, such as a header upload button and a setting page avatar picker. It is no longer necessary to manually keep configurations in sync. Now you can set it once at the provider level and have it apply at the per-component level. If needed, users can override it per-component for when the occasion requires different configurations. Additionally, the editor flags a mismatched prop before running the app. 

See the example below to learn how to wrap your app once so that every picker component underneath it inherits the same configuration.

import { FilestackProvider, PickerDropPane } from 'filestack-react';

function App() {
  return (
   <FilestackProvider 
    apikey={'YOUR_API_KEY'}
    onUploadDone={(result) => console.log(result.filesUploaded)}
   >
     <UploadWidget  />  
   </FilestackProvider>
);
}
// No need to repeat apikey or onUploadDone here - inherited from FilestackProvider
function UploadWidget() {
return <PickerDropPane />;
}

Along with v7, the entire SDK has been changed to support TypeScript/TSX (previously JavaScript/JSX). Type declaration files (.d.ts) are now included in the package. Ensuring autocomplete and type safety from the start. 

The package bundles its own declarations. Install it, import it, and ready to go. No @types/* needed, see an example below.

import {  
  PickerOverlay,
  FilestackProvider,
type PickerOverlayProps,
type PickerResponse,
type PickerOptions,
type ClientOptions
} from 'filestack-react';

const pickerOptions: PickerOptions = { maxFiles: 5, accept: ['image/*']};
const clientOptions: ClientOptions = { cname: 'cdn.example.com' };

const handleUploadDone = (res: PickerResponse) => {
 res.filesUploaded.forEach((file) => console.log(file.url));
};

const App = () => (  
 <FilestackProvider apikey={process.env.REACT_APP_FILESTACK_KEY!}>
   <PickerOverlay
     pickerOptions={pickerOptions} 
     clientOptions={clientOptions}
     onUploadDone={handleUploadDone}
     onError={ (err) => console.error(err)}
 /> 
 </ FilestackProvider> 
);

Since PickerOptions, ClientOptions, and PickerResponse come from filestack-js, you get autocomplete on every nested option (maxFiles, accept, fromSources, transformations, and the rest).

Note: Read this carefully before upgrading.

Most applications using v6 require two main changes before upgrading to v7: installing the filestack-js and renaming one callback. 

1. Install it by using the following command:

npm install filestack-react@7.0.0 filestack-js@^4.0.0

2. Check your React and Node versions. Note that the React peer dependency range has changed and now requires react:^18.3.1 || ^19.0.0 and react-dom:^18.3.1 || ^19.0.0

Note: If you are using a version of React lower than 18.3.1, you must first upgrade to 18.3.1. React 16 and 17 are no longer supported.

3. Update the Filestack dependencies by using the following command (Ensure the Node version is 18.3.1 or higher):

npm install filestack-react@7.0.0 filestack-js@^4.0.0
# or
yarn  add filestack-react@^7.0.0 filestack-js@^4.0.0

npm uninstall @types/filestack-react

8. Run your test suite. With the TypeScript rewrite, you may see new type errors surfaced in your own code where prop types were previously unchecked at compile time.