Skip to content
Rails wrapper for Uploadcare
Ruby HTML CSS JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin rename group.urls method; update Jun 20, 2016
config Fix error when running `rails generate uploadcare_config` without a c… Oct 21, 2017
gemfiles - clean up spec environment initialization code Jun 2, 2018
lib Allow to use multiple files or groups (#74) Oct 1, 2018
spec Allow to use multiple files or groups (#74) Oct 1, 2018
.travis.yml - clean up spec environment initialization code Jun 2, 2018
Gemfile one more time Jul 15, 2016
Guardfile * updated specs Jun 20, 2016
LICENSE Fix a few spelling errors Dec 10, 2018
Rakefile travis ci testing Apr 2, 2014
uploadcare-rails.gemspec prepare 1.2.0-alpha2 release May 28, 2018

Build Status Uploadcare stack on StackShare

A Ruby on Rails plugin for Uploadcare service. Based on uploadcare-ruby gem (general purpose wrapper for Uploadcare API)

Try our demo app.


Add this line to your application's Gemfile:

gem 'uploadcare-rails', "~> 1.1"

And then execute:

$ bundle install

Or install it yourself:

$ gem install uploadcare-rails -v 1.2.1


Uploadcare requires to store all related config in one single yml file. You should create uploadcare.yml in your config folder. Just run

$ bundle exec rails g uploadcare_config

Or create it yourself - it should contain something like:

# config/uploadcare.yml
defaults: &defaults
  public_key: "demopublickey"
  private_key: "demoprivatekey"

  <<: *defaults

  <<: *defaults
  autostore: false

  <<: *defaults

Only two config settings are required: public and private keys. All other posible options are listed here. Config file created by generator also contains a list of all options with default values. Note that global settings are used for internal API calls and as default config for widget. Any instance of widget can have separate set of config that will override app-wide settings if needed.

Including widgets and widget configuration

First you should add Uploadcare widget to the page. There are two way of doing that:

Load widget from our CDN (recommended)

Just call helper in head of application layout (or anywhere else if needed):

<!DOCTYPE html>
  <%= stylesheet_link_tag    "application", media: "all" %>
  <%= javascript_include_tag "application" %>
  <%= csrf_meta_tags %>
  <%= include_uploadcare_widget_from_cdn version: "3.x", min: true %>
    results in:
    <script src=""></script>

Uploadcare widget depends on jQuery. Rails 5.1 dropped jQuery as a default dependency so if you use rails >= 5.1 make sure that jQuery is loaded or use uploadcare widget with jQuery bundeled.

Download and append widget manually to your pipeline.

You may download (e.g. and serve the widget yourself along with your other assets.

Widget configuration

Next step is including application-wide settings in page. Just call :uploadcare_settings helper in head of layout:

<!DOCTYPE html>
  <%= stylesheet_link_tag    "application", media: "all" %>
  <%= javascript_include_tag "application" %>
  <%= csrf_meta_tags %>
  <%= include_uploadcare_widget_from_cdn version: "3.x", min: true %>
  <%= uploadcare_settings %>
    results in:
        UPLOADCARE_PUBLIC_KEY = "demopublickey";
        .... more settings ...

Here you can read more about configuration.


Basic tag

Basic usage of Uploadcare gem is very simple. Remember that uploader returns you a simple string with cdn url of a file or group.

<%= uploadcare_uploader_field :post, :file %>
  results in:
  <input data-path-value="true" id="post_file" name="post[file]" role="uploadcare-uploader" type="hidden">
  <div class="uploadcare-widget" style="display: none;" data-status="ready">

This tag will result in:

# =>

Form tags

We have smart and fancy form builder helpers for you.

<%= form_for(@post) do |f| %>

  <div class="field">
    <%= f.label :title %><br>
    <%= f.text_field :title %>
  <div class="field">
    <%= f.label :file %><br>
    <%= f.uploadcare_field :file %>
  <div class="actions">
    <%= f.submit %>
<% end %>

This will result in Uploadcare uploader with either single file uploader (if model has uploadcare file attribute) or multiple uploader (if model has uploadcare group attribute). Note that groups and single files behave differently, so you can not mix one with another (in version 1.0 anyway).

You can also use universal builder helper:

# simple uploadcare uploader with no smart suggestions about type of result object:
f.uploadcare_uploader :file

# you can set multiple options as you want:
f.uploadcare_uploader :file, :data => {:multiple => true}

# also there is uploadcare namespace for options
# note that this namespace will be translated into data- attributes
f.uploadcare_uploader :file, :uploadcare => {:multiple => true}
# => will result in "data-multiple"="true"

# uploadcare namespace have a higher priority and will override data- attributes
f.uploadcare_uploader :file, :data => {:multiple => true}, :uploadcare => {:multiple => false}
# => will result in "data-multiple"="false"

And two other helpers:

# forse-set "data-multiple" to false
f.uploadcare_single_uploader_field :file

# forse-set "data-multiple" to false
f.uploadcare_multiple_uploader_field :file

What options are avaliable with uploadcare namespace for uploader? Well, honestly there is no validation in version 1.0 and all options from that namespace are simply translated into data- attributes. More on valid options you can read in widget docs.


Both :has_uploadcare_file and :has_uploadcare_group defined for model will return an either Uploadcare::Rails::File or Uploadcare::Rails::Group objects. Both are derrived from Uploadcare::File and Uploadcare::Group respectively, with some helpers to fit in Rails enviroment.

File object

Basicly it has same methods as Uploadcare::File object, with several additions. Firstly, string representation of file is cdn url.

# calling the object in templates will respond with cdn_url string
# instead of object serialization
# in the template call:
# =>

# so
# is a perfectly valid usage
# => <img src="">

Group object

What is different? Not much.

# calling group (or whatever attribute name you choose) in the template
# => 19cde26d-e41b-4cf5-923e-f58729c0522a~2

Note that explicit loading of group is required for getting access for group files:

# calling group (or whatever attribute name you choose) in the template
@group =
# => [#<Uploadcare::Rails::File ...]

Then you can iterate through files:

  <% @group.files.each do |file|%>
      <%= image_tag(file.cdn_url) %>
  <% end %>

However, you can get links to all of the images without API calls.

  <%- do |url|%>
      <%= image_tag(url) %>
  <% end %>


The full documentation is available here.

Operations supported by gem:

  • format: (jpeg|png)
  • quality: (normal|better|best|lighter|lightest)
  • progressive: (yes|no)
  • preview: (200x150)
  • resize: (150x|x200|150x200)
  • inline: documentation

For single file you can pass additional arguments while calling file url:

  • @post.file.url(preview: '300x300')
  • @post.file.url(quality: :normal)
  • @post.file.url(resize: '150x')

Or you can combine existing operation helpers with inline operations from documentation:

    preview: '900x900',
    resize: '150x',
    inline: "/progressive/yes/"

You can pass operations to all images in group:

  <%- '150x').each do |url|%>
      <%= image_tag(url) %>
  <% end %>

Future releases:

We have big plans for future:

  • Localizations for widget directly from rails i18n;
  • More render and output helpers for html pages and api responses;

So stay tuned!


This is open source, fork, hack, request a pull, receive a discount).

You can’t perform that action at this time.