Documentation
General Instructions
Setup

To use the add-on you need to add the javascript snippet and create a hidden input with the class of simple-file-upload.

1. Add the javascript snippet

Sign up for Simple File Upload and get your API key. Then add the javascript snippet in the head of your website:

      <script src="https://app.simplefileupload.com/buckets/YOURCUSTOMAPIKEY.js"></script>
  

2. Create a hidden input

You can either create a hidden input with class simple-file-upload or automatically attach to existing file inputs. It is highly recommended that you create a new hidden input with the simple-file-upload class because this allows you to preview your existing file in the dropzone. This means that on a form submit failure, the image will persist for the user.

For example, to add an avatar to a model you can create a hidden input tag with the following syntax:

HTML
<input type="hidden" name="avatar_url" id="avatar_url" class="simple-file-upload">
3. Save the returned URL to your database.

The uploader works by populating the value parameter of the hidden input with the url of the dropped file.
For example, if you have an html element of this structure:

<input type="hidden" id="user_avatar_url" name="user[avatar_url]" class="simple-file-upload">

After a file is uploaded the element will become:

<input type="hidden" id="user_avatar_url" name="user[avatar_url]" class="simple-file-upload" value="https://static.files-simplefileupload.com/randomstring/filename.png">

In order to reference this file elsewhere in the application, you need to save the value parameter to your database.

4. View or download the user uploaded file

If the file is an image, you can view it using a standard image tag:

<%= image_tag current_user.avatar_url, height: 20, width: 20%>

If the file is not an image, the file is accessible directly via the url.

More Information

Adding direct uploads to an application allows you to offload the storage of static files from your app. This is crucial on Heroku, because your app’s dynos have an ephemeral filesystem. This means that all files that aren’t part of your application’s slug are lost whenever a dyno restarts or is replaced (this happens at least once daily).
Simple File Upload uses direct uploads. In a direct upload, a file is uploaded to S3 from a user's browser, without first passing through your app. This method is recommended by Heroku Dev Center here. Simple File Upload handles all of the direct upload processing for you. You do not need a cloud storage account. Simple File Upload provides the dropzone UI, allows your users to drop images or select images from a local filesystem, and returns a url of the image behind a CDN.

Ruby Instructions
Setup

To use the add-on you need to add the javascript snippet and create a hidden input with the class of simple-file-upload.

1. Add the javascript snippet

Sign up for Simple File Upload and get your API key. Then add the javascript snippet in the head of your website:

      <script src="https://app.simplefileupload.com/buckets/YOURCUSTOMAPIKEY.js"></script>
  

2. Create a file input

If you are using Ruby on Rails with a model backed form as below:

<%= form_with model: @user do |form| %>

Add the hidden input field using the form variable:

<%= form.hidden_field :avatar_url, class: "simple-file-upload" %>

This will automatically create the html element:

<input type="hidden" name="user[avatar_url]" id="user_avatar_url" class="simple-file-upload">

If you are using Ruby on Rails without a model backed form you can use a hidden_field_tag helper:

<%= hidden_field_tag "avatar_url" class="simple-file-upload" %>

which becomes the html element:

<input type="hidden" name="avatar_url" id="avatar_url" class="simple-file-upload">

3. Save the returned URL to your database

Using the example of adding an avatar to a user, add this url as a string to your users table:

rails generate migration AddAvatarUrlToUsers avatar_url:string

migrate the database:
rails db:migrate

If you are using Ruby on Rails strong parameters, you must add the new url to the permitted params:

def user_params
params.require(:user).permit( :avatar_url)
end

If you are using Devise as your User model in Ruby on rails, modify your permitted parameters in application_controller.rb

devise_parameter_sanitizer.permit(:account_update, keys: [:name, :avatar_url])

Using the avatar_url example the existing

<input type="hidden" name="user[avatar_url]" id="user_avatar_url" class="simple-file-upload"> element becomes
<input type="hidden" id="user_avatar_url" name="user[avatar_url]" class="simple-file-upload" value="https://static.files-simplefileupload.com/randomString/filename.extension">
where "https://static.files-simplefileupload.com/randomString/filename.extension"is the url of the file the user uploaded. When you submit your form, this value will be available as a normal parmeter.

React Instructions

There is a React component for Simple File Upload called react-simple-file-upload. You can install it with npm or yarn:
npm install react-simple-file-upload

Once installed, you can import and use the package. Once uploaded, the file will be available in the onSuccess handler.

import { SimpleFileUpload } from 'react-simple-file-upload'

  <SimpleFileUpload
    apiKey="..."
    onSuccess={handleFile}
  />

  function handleFile(url){
    console.log('The URL of the file is ' + url)
  }

Save the URL

Once uploaded, the file can be accessed at the returned URL.

Frequently Asked Questions

How do I remove the preview after the file has been uploaded?

The widget accepts preview: false.
If using the React component:

<SimpleFileUpload
    apiKey="YOURAPIKEY"
    preview="false"
    onSuccess={setFile}
/>

If using the javascript snippet, when you create your form element add a data attribute of preview: false.

<input class="simple-file-upload" data-preview="false" type="hidden"  name="user[avatar_url]" id="user_avatar_url">

Or with Rails form helpers:

<%= f.hidden_field :avatar_url, class: "simple-file-upload", data: { preview: false }%>
How do I change the size of the displayed dropzone?

The widget accepts a width and height parameter.
If using the React component:

  <SimpleFileUpload
    apiKey="YOURAPIKEY"
    width="300"
    height="300"
    onSuccess={setFile}
  >

Javascript snippet: coming soon.

Does the widget work with typescript?

The widget does not support typescript out of the box, but customers have had success using the following typescript definition:

react-simple-file-upload.d.ts

declare module 'react-simple-file-upload' {
    import React from "react";

    export default class SimpleFileUpload extends React.Component<UploadProps & any, any> {
        constructor(props: any) {
            super(props);
        }

        onSuccess(): string
    }

    interface UploadProps {
        apiKey: any
        onSuccess: any
    }
}
Can users delete their files after upload?

Not at this time. This feature is coming, if this is important to you please email us and let us know!

Examples

Working Rails application

See the uploader working in a Rails application here. You need to replace YOURAPIKEY in the javascript with your api key provided.

React application

See a working example of the component here (note: files in the code sandbox are not persisted, you must use your own API key!)