Filestack for React ⚛️

Overview

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.

Usage

Compatibility Notice: The filestack-react library currently supports React versions 16, 17, and 18. If you are starting a new project, please ensure you are using a compatible version of React. Support for React 19 is coming soon.

Installation

Install the package from NPM.

npm install filestack-react

Implementation

Import a picker component and add it to your app. The only required prop is your Filestack API key.

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

Component Props

Customize the picker’s behavior and appearance using these props.

Key	Type	Required	Description
`apikey`	String	Yes	Your Filestack API key.
`clientOptions`	Object	No	Options to initialize the filestack-js client. See docs.
`pickerOptions`	Object	No	Controls the picker’s behavior and UI. See docs for all available settings.
`onSuccess`	Function	No	Deprecated A function called after a successful action. Use `onUploadDone` instead.
`onUploadDone`	Function	No	Callback function that runs when all files have been successfully uploaded. Receives the result object.
`onError`	Function	No	Callback function that runs when an error occurs.

Picker Components & Examples

The library provides three main components to render the picker in different ways.

PickerOverlay

Renders the picker in a modal that overlays your application.

import { PickerOverlay } from 'filestack-react'; <PickerOverlay apikey={'YOUR_APIKEY'} />

PickerInline

Renders the picker directly inside a container in your application’s DOM.

import { PickerInline } from 'filestack-react'; <PickerInline apikey={'YOUR_APIKEY'} />

PickerDropPane

Renders a drag-and-drop area for uploads.

import { PickerDropPane } from 'filestack-react'; <PickerDropPane apikey={'YOUR_APIKEY'} />

Custom Container

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>

Using the filestack-js Client

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); });

Server-Side Rendering (SSR)

If you are using filestack-react in an SSR project (like Next.js or Gatsby), you may need to dynamically import the component to avoid errors related to the window object. For known workarounds, please see these issues on GitHub:

Migration Guides

Migrating from v3/v4 to Latest

Key props have been renamed for consistency.

Old Prop (v3/v4)	New Prop	Comment
`actionOptions`	`pickerOptions`	Unified naming for picker configuration.
`action`	N/A	The default picker action is now always ‘pick’.
`customRender`	N/A	Clients are now responsible for rendering logic.
`componentDisplayMode`	N/A	Render logic is handled by the client.

Migrating from v1/v2 to v3+

Props were re-structured for clarity.

Old Prop (v1/v2)	New Prop	Comment
`mode`	`actionOptions`	Emphasizes association with a picker ‘action’.
`options.security`	`clientOptions.security`	Security options are now grouped under clientOptions.
`buttonText`	`componentDisplayMode.customText`	Use the componentDisplayMode option. (Deprecated in v4+)
`buttonClass`	`componentDisplayMode.customClass`	Use the componentDisplayMode option. (Deprecated in v4+)
`render`	`customRender`	Use the customRender prop. (Deprecated in v4+)

More Resources

Live Demo: Try the picker on CodePen (Note: this demo may not reflect the latest version).
Development: All components are located in the src/picker/ directory of the repository. Run npm run build to compile changes.
Contribution: Contributions and ideas are welcome! The project follows the conventional commits specification.