Table of Contents

• Overview
• Usage
  • Props
  • Examples
  • filestack-js Client
  • SSR
  • Migration from 3.x.x and 4.x.x
  • Migration from 1.x.x and 2.x.x
• Live demo
• Development
• Documentation
• Contribution
• Future

Overview

filestack-react is a wrapper on filestack-js sdk which allow you to integrate with Filestack service in just a few lines of code. Almost all you can do with filestack-js you can do with this component.

Usage

Install it through NPM

npm install filestack-react

then just insert into your app

import { PickerOverlay } from 'filestack-react';

<PickerOverlay
  apikey={YOUR_API_KEY}
  onSuccess={(res) => console.log(res)}
  onUploadDone={(res) => console.log(res)}
/>

Props

| Key | Type | Required | Default | Description | |----------------------------------|---------------|----------|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | apikey | String | true | | Filestack api key | | clientOptions | Object | false | | https://filestack.github.io/filestack-js/interfaces/clientoptions.html | | pickerOptions | Object | false | | https://filestack.github.io/filestack-js/interfaces/pickeroptions.html | | @deprecated onSuccess | Function | false | result => console.log(result) | A function to be called after successful completed action | | onUploadDone | Function | false | result => console.log(result) | Called when all files have been uploaded | | onError | Function | false | error => console.error(error) | A function to be called when error occurs | | onError | Function | false | error => console.error(error) | A function to be called when error occurs |

Examples

Render basic Overlay Picker

<PickerOverlay apikey='YOUR_APIKEY'/>

Render basic Inline Picker

<PickerInline apikey='YOUR_APIKEY'/>

Render basic Drop Pane Picker

<PickerDropPane apikey='YOUR_APIKEY'/>

Show picker directly and embed it inside specific container

<PickerInline apikey='YOUR_APIKEY'><div className="your-container"></div></PickerInline>

filestack-js Client

If you need to use Client just try

import { client } from 'filestack-react';

SSR

If you need to use filestack-react with SSR project or site generators like Gatsby check some workarounds in this issues issue57 issue65

Migration from 3.x.x and 4.x.x

| 3.x.x | 4.0.0 | Comment | |----------------|----------------------------------|-------------------------------------------------------------------------------| | apikey | apikey | | | actionOptions | pickerOptions | We want to be consistent with other filestack libs | | clientOptions | clientOptions | | | onSuccess | onSuccess | | | onError | onError | | | N/A | children | Children prop will be used now in case you'll want to use specific container | | action | N/A | Default picker action will be 'pick' always | | file | N/A | Removed | | source | N/A | Removed | | customRender | N/A | Removed, from now on clients will be responsible for rendering | | componentDisplayMode | N/A | Removed, from now on clients will be responsible for rendering |

Migration from 1.x.x and 2.x.x

One of the changes introduced in the new version are rethinked props that the component accepts, so that the use of the component is as straightforward as possible. Below you will find information about what happened to each of the options available in 2.x.x :

| 2.x.x | 3.0.0 | Comment | |----------------|----------------------------------|-------------------------------------------------------------------------------| | apikey | apikey | | | mode | action | | | options | actionOptions | We want to emphasize that this option is associated with 'action' | | preload | N/A | Now, component is at default preloading necessary js assets, styles, images | | file | file | | | onSuccess | onSuccess | | | onError | onError | | | options.handle | source | Handle or url used by specific action is now stored in separate prop | | options.url | source | Handle or url used by specific action is now stored in separate prop | | security | clientOptions.security | Options used to initialize filestack client are now grouped in ‘clientOptions’ | | buttonText | componentDisplayMode.customText | Use componentDisplayMode option (see examples) | | buttonClass | componentDisplayMode.customClass | Use componentDisplayMode option (see examples) | | cname | clientOptions.cname | Options used to initialize filestack client are now grouped in ‘clientOptions’ | | sessionCache | clientOptions.sessionCache | Options used to initialize filestack client are now grouped in ‘clientOptions’ | | render | customRender | | | children | N/A | Use customRender instead |

Live demo

Check demo at codepen https://codepen.io/Filestack/pen/KEpVdR - needs to be updated for 4.0 version

Development

All components are located inside src/picker/

After you add some changes just type

npm run build

Be sure that your change doesn't break existing tests and are compatible with linter

npm run test

Documentation

You can find info about available options for actions (Client class methods) in https://filestack.github.io/filestack-js/

Contribution

Any your contributions or ideas are more than welcome. Please consider that we follow the conventional commits specification to ensure consistent commit messages and changelog formatting.

Future

Current ideas:

• Better support for SSR, static site generator and isomorphic apps