RubyGems Travis CI Coveralls Code Climate

Adds form, image_tag, and download/save helpers to help you get up and running with in Rails.


Add this line to your application's Gemfile:

gem 'filepicker-rails'

And then execute:

$ bundle

Or install it yourself as:

$ gem install filepicker-rails

Add the javascript library to your layout:

<%= filepicker_js_include_tag %>

Set your API Key in config/application.rb:

config.filepicker_rails.api_key = "Your API Key"


First create a migration to add the field that will hold your URL

Run the Rails migration generator from the command line:

$ rails g migration AddNameOfAttrForFilepickerUrlToUser

Then add a column to the model's table of type :string:

class AddNameOfAttrForFilepickerUrlToUser < ActiveRecord::Migration
  def change
    add_column :user, :filepicker_url, :string

Adding an upload field to your form:

<%= form_for @user do |f| %>
    <%= f.label :filepicker_url, "Upload Your Avatar:" %>
    <%= f.filepicker_field :filepicker_url %> <!-- User#filepicker_url is a regular string column -->

  <%= f.submit %>
<% end %>

The filepicker_field accepts a options parameter, click here to see all the valid options.

Displaying an image:

<%= filepicker_image_tag @user.filepicker_url, w: 160, h: 160, fit: 'clip' %>

The filepicker_image_tag accepts a options parameter, click here to see all the valid options.

Accessing FilePicker File with OnChange:

Javascript code in the onchange field acts as a callback, which is called on upload completion. You can specify onchange either in the ERB template (as shown below), or unobtrusively via jQuery's change event.

<%= form_for @user do |f| %>
    <%= f.label :filepicker_url, "Upload Your Avatar:" %>
    <%= f.filepicker_field :filepicker_url, onchange: 'onPhotoUpload(event)' %>

  <%= f.submit %>
<% end %>

The callback is called with a special 'event' variable. The variable has a fpfiles (or if not multiple, also fpfile) attribute with information about the files (jQuery users: look under event.originalEvent).

Example fpfiles object:

    url: 'https://...',
    data: {
        filename: 'filename.txt',
        size: 100,
        type: 'text/plain'
    url: 'https://...',
    data: {
        filename: 'filename2.jpg',
        size: 9000,
        type: 'image/jpeg'

Allowing the user to download a file (or upload it to any of the supported services)

<%= filepicker_save_button "Save", @user.filepicker_url, "image/jpg" %>

The filepicker_save_button accepts a options parameter, click here to see all the valid options.


Set your CDN Path in config/production.rb (CDN usage):

config.filepicker_rails.cdn_host = "Your CDN host name"


To use the filepicker policies follow this instructions.

Set your Secret Key in config/application.rb

config.filepicker_rails.secret_key = "Your Secret Key"

Expiry time

By default the expiry time is 10 minutes. If you need to change the expiry time this should be an integer and it is expressed in seconds since the Epoch.

So you can do something like that to set the expiry time to 5 minutes.

config.filepicker_rails.expiry = -> { ( + 5.minutes).to_i }

If you need always the same url, a static expiry time, to do some cache. You can set a date starting of the Epoch.

-> { 100.years.since( }

The argument need to be a callable.


See a simple demo app repo


You can view the Filepicker::Rails documentation in RDoc format here:


Filepicker::Rails follow the Semantic Versioning.


If you have problems, please create a Github Issue.


Please see for details.


Thank you to all the contributors.