Documentation

General Instructions

Setup

Add the javascript snippet to the head of your site and create a hidden input with the class of simple-file-upload.

1. Add the javascript snippet

Copy the following line to the head of your site.

<script src="https://app.simplefileupload.com/buckets/{{yourKey}}.js"></script>

2. Create a hidden input

Create a hidden input with class simple-file-upload

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://subdomain.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

Add the javascript snippet to the head of your site and create a hidden input with the class of simple-file-upload.

1. Add the javascript snippet

Copy the following line to the head of your site.

<script src="https://app.simplefileupload.com/buckets/{{yourKey}}.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://subdomain.files-simplefileupload.com/randomString/filename.extension">

where "https://subdomain.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.

Javascript Events

On successful file upload a custom event is fired called fileUploadSuccess.
An example of how to listen to the event is shared below:

Give the form element a custom id:

<input type="hidden" id="test-files-uploader" class="simple-file-upload">

Grab the id of the form input:

  const el = document.getElementById("test-files-uploader");

Listen to the event and respond accordingly:

  el.addEventListener("fileUploadSuccess", function (e) {
    console.log(this.value)
  });

Frequently Asked Questions

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

The widget accepts a data attribute of preview: false.
If using the React component:

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

Javascript snippet: 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">

Using 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 data width and height parameter.
If using the React component:

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

Javascript snippet: Add a data width and height parameter to the hidden input.

<input class="simple-file-upload" data-width="50" data-height="50"
type="hidden" value="" name="user[avatar_url]" id="user_avatar_url">

Using Rails form helpers:

<div class="form-group">
    <%= f.hidden_field :avatar_url, class: "simple-file-upload", data: {width: "50", height: "50"}%>
</div>
How can I delete files?

For security purposes, files can only be deleted from an authenticated API request. Please see the api documentation

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

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!)