Widget customization

  • This documentation is for the version 3.1.4 of the widget. If you're looking for the widget v2 docs, check here.

Uploadcare widget and dialog are shown on your web app and we understand the importance of seamless look and feel. There always was possibility to modify widget appearance through CSS and starting with version 0.16.0 we extend customization features.

Embed Dialog in Page

By default after user clicks on Uploadcare widget, modal dialog is shown covering the rest of page with semi-transparent background. This is ok if upload field is one of many in a form. But if upload is main action for the page (e.g. wizard step) initial click becomes unnecessary. For this case we allow showing uploading panel directly on the page.

<div id="uploader-placeholder">Uploading. Please wait...</div>

In this case panel will replace DOM element with uploader-placeholder id and return it back after user have chosen a file. This can be used to show some indication of upload process. Another difference is that unlike dialog, panel can be closed only by choosing a file.

Uploading. Please wait...


The panel may look ugly as it has sharp border, but you can change it’s appearance via CSS. Add something like this:

#uploader-styling {
  margin-top: 10px;
#uploader-styling .uploadcare--panel,
#uploader-styling .uploadcare--menu__item,
#uploader-styling .uploadcare--menu__items {
  background-color: transparent;
  border: 0;
#uploader-styling .uploadcare--panel {
  flex-direction: column;
#uploader-styling .uploadcare--menu {
  width: 100%;
  height: 60px;
  min-height: 60px;
#uploader-styling .uploadcare--menu__items {
  padding-right: 0;
  flex-direction: row;
.uploadcare--tab_name_favorites {
  flex-direction: row;
  flex-wrap: wrap;
  justify-content: flex-start;
  overflow: auto;
.favorite-files-image {
  width: 140px;
  height: 140px;
  margin: 10px;
  padding: 5px;
  color: rgba(0,0,0,.4);
  box-shadow: 0 6px 20px -3px;
  cursor: pointer;
.favorite-files-image:hover {
  color: rgba(0,100,200,.5);
Uploading. Please wait...

Some of the dialog elements are rendered inside iframes from our servers, therefore their customization via CSS is not available. But you can use tabsCss methods to inject CSS inside iframes.

Custom Tabs

When you are happy with how dialog or panel looks, you may want to change its behavior. Now you can add your own tabs to it to have full control. To do this you need to register a named tab and specify its name in list of enabled tabs.

<div id="uploader-placeholder">Uploading. Please wait...</div>
function favoriteFiles(container, button, dialogApi, settings) {
uploadcare.registerTab('favorites', favoriteFiles);
uploadcare.openPanel('#uploader-placeholder', null, {
  tabs: 'favorites file facebook dropbox gdrive instagram vk',
  favoriteFiles: [...]

Suppose you need a tab with the list of previously uploaded images. You can pass a list of file ids via settings object. When user selects a file you can inform dialog via dialogApi.

function favoriteFiles(container, button, dialogApi, settings) {
  $.each(settings.favoriteFiles, function(i, uuid) {
    container.append($('<img>', {
        'class': 'favorite-files-image',
        'src': settings.cdnBase + '/' + uuid + '/-/scale_crop/280x280/center/',
      .on('click', function(e) {
        dialogApi.addFiles([uploadcare.fileFrom('uploaded', uuid, settings)])

You can tune the look of your tab via CSS. In case you're willing to use custom icons, make use of <svg> and <symbol>. Check out the example below.

<svg width="0" height="0" style="position:absolute">
  <symbol id="uploadcare--icon-favorites" viewBox="0 0 32 32">
    <path d="M 16 22.928 L 23.416 27.4 L 21.454 18.965 L 28 13.292 L 19.37 12.552 L 16 4.6 L 12.629 12.552 L 4 13.292 L 10.546 18.965 L 8.584 27.4 Z"/>
.uploadcare--menu__item_tab_favorites.uploadcare--menu__item_current {
  color: #f0cb3c;
Uploading. Please wait...


We're always happy to help with code or other questions you might have! Search our site for more information or send us an email!