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

Two custom events are emitted - when an upload starts and when a file has uploaded successfully.

1. The event fileUploadStarted is emitted when the user starts an upload.
2. The event fileUploadSuccess is emitted when the file has uploaded successfully.

An example of how to listen to these 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");

To listen to the file upload started event:

   el.addEventListener("fileUploadStarted", function (e) {
    alert('file upload started' + this.value)
  });

To listen to the file upload success event:

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