filestack-react

React component which allow you to easily integrate powerful filestack-api into your app.

Table of Contents

Overview
Usage
Live demo
Development
Documentation
Contributing
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 ReactFilestack from 'filestack-react';

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

Props

Key	Type	Required	Default	Description
apikey	String	true		Filestack api key
action	String	false	'pick'	A method from Client class. One of 'transform','retrieve','metadata','storeUrl','upload','remove','pick','removeMetadata','preview','logout'
actionOptions	Object	false		An action (client method) specific options object eg. PickerOptions, TransformOptions etc.
componentDisplayMode	Object			Determines how will be wrapper component displayed
componentDisplayMode.type	String	false	'button'	It can be 'button', 'link' or 'immediate'
componentDisplayMode.customText	String	false	'Pick file'	If type is 'button' or 'link' you can set text for it
componentDisplayMode.customClass	String	false	'filestack-react'	If type is 'button' or 'link' you can set class for it
onSuccess	Function	false	result => console.log(result)	A function to be called after successful completed action
onError	Function	false	error => console.error(error)	A function to be called when error occurs
clientOptions	Object			Filestack client options used for an every action
clientOptions.cname	String	false		Check cname
clientOptions.security	Security	false		Check security
clientOptions.sessionCache	Boolean	false		Check sessionCache
file	Object	false		Use it to insert a file object for 'upload' action
source	String	false		Use it to pass for some actions handle or external url
customRender	Function	false		Use it if you need custom html structure

Examples

Picker with custom designed button

<ReactFilestack
  apikey={YOUR_API_KEY}
  actionOptions={PickerOptions}
  componentDisplayMode={{
      type: 'button',
      customText: 'Click here to open picker',
      customClass: 'some-custom-class'
  }}
  onSuccess={this.yourCallbackFunction}
/>

Picker with custom wrapper

<ReactFilestack
  apikey={YOUR_API_KEY}
  actionOptions={PickerOptions}
  customRender={({ onPick }) => (
    <div>
      <strong>Find an avatar</strong>
      <button onClick={onPick}>Pick</button>
    </div>
  )}
  onSuccess={this.yourCallbackFunction}
/>

Show picker directly after component is mounted

<ReactFilestack
  apikey={YOUR_API_KEY}
  componentDisplayMode={{
    type: 'immediate'
  }}/>

Show picker directly and embed it inside specific container

<ReactFilestack
  apikey={YOUR_API_KEY}
  componentDisplayMode={{
    type: 'immediate'
  }}
  actionOptions={{
    displayMode: "inline",
    container: "embedded"
  }}/>

Transformation of external url with security

<ReactFilestack
  apikey={YOUR_API_KEY}
  componentDisplayMode={{
    type: 'immediate'
  }}
  action='transform'
  actionOptions= {{
    resize: {
      width: 250
    },
    flip: true
  }}
  clientOptions={{
    security: {
      policy: 'YOUR_POLICY',
      signature: 'YOUR_SIGNATURE'
    }
  }}
  source='https://upload.wikimedia.org/wikipedia/commons/c/cf/Pears.jpg'
  onSuccess={(res) => console.log(res)}/>

filestack-js Client

If you need to use Client just try

import ReactFilestack, { 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 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 neccessary 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

Development

The whole componenst is located inside src/ReactFilestack.jsx

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

npm run lint

Documentation

You can find info about avalaible 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

mpoisot/filestack-react