Widget customization

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

Widget customization

Uploadcare Widget is designed for integrations: its dialog can then be found around your web app. We understand the importance of seamless UX/UI and provide you with a good number of widget customization options that cover both widget appearance and behavior. The look of the widget can be changed via CSS, and our interactive configurator is a great starting point in controlling how your widget behaves.

Here are configuration options we find important:

  • Embed widget in a page, when you want the widget to be shown on your page without an initial click.
  • Styling options, when you plan to change the look of the widget.
  • Custom tabs, when you want to design a widget tab that does something specific.

Embed widget in a page

The default behavior is when the widget dialog appears on user click. This also covers the rest of the page with a semi-transparent background. It is a good fit when you use the widget to fill in a single form field out of many.

However, uploading user-generated content may be the very purpose of a whole page, like a step in some wizard. That is when we provide you with the ability to show the widget on a page without any preceding clicks. The thing is called panel.

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

This replaces your DOM element with the uploadcare-placeholder id and then puts it in place once a user selects a file. This can be used to show some indication of the uploading process, for instance. Also, unlike the dialog, widget panel can be closed by simply selecting a file.

Uploading. Please wait...

Styling options

That’s just an example of altering the look of your widget. Say, you embedded a widget in your page as a panel. And, now you don’t like its look because of the sharp border. You are free to change the appearance via CSS. It goes 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 to iframes from our servers which does not allow any CSS customization. However, we provide a set of specific methods to inject CSS into iframes.

Custom tabs

The widget might show up when you want it and look the way you want it, how about adding custom behaviors? That’s done by adding your own tabs to the widget interface. You will need to register a tab under some name and add this name to the list of your widget 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: [...]

The following example covers creating a custom tab providing you with a list of files uploaded via your widget. You can pass a list of file IDs via the settings object. When a user selects a file for upload, you can pass this info to the dialog using 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 also tune the look of your tab via CSS. In case you're willing to add 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...