Migrating Uploadcare Widget From v2 to v3
On this page
Uploadcare Widget v2 is in many aspects compatible with v3:
settings and input
didn’t change at all while JavaScript API was modified just a bit.
However, v3 has many changes related to the HTML markup and styles of the widget.
Also, we’ve completely removed external .png
files like icons-active@2x.png
: instead, we use SVG.
- In case you used the widget and its JavaScript API without customizing any styles, you can update to the third version right away.
You can always check out the complete widget changelog here. If you’re willing to learn more about installing Uploadcare Widget, check out our docs.
HTML markup of widget UI
With Uploadcare Widget v3 we used the classical BEM methodology.
BEM (Block, Element, Modifier) is a component-based approach to web development.
UI of the widget, therefore, was divided into independent blocks,
like widget
, dialog
, file
, etc.
All classes now have the uploadcare--
prefix.
Since we’ve implemented many changes, you might first want to take a look at the stylesheets under the blocks folder. This will update you on all kinds of redesigned blocks and elements.
Also, you can drop us a line: we’ll gladly answer your questions.
Widget
The widget now has the uploadcare--widget
class instead of the uploadcare-widget
class.
The widget has also a uploadcare--widget_status_*
class for different states:
ready
, loaded
, started
, error
.
The buttons inside the widget are button
instead div
now with
class uploadcare--widget__button
and also can be on of three type:
uploadcare--widget__button_type_open
,uploadcare--widget__button_type_cancel
,uploadcare--widget__button_type_remove
.
These elements are now parts of the widget:
uploadcare--widget__dragndrop-area
,uploadcare--widget__progress
,uploadcare--widget__text
.
When a file gets uploaded (widget is switched to the loaded
state),
uploadcare--widget__text
holds uploadcare--widget__file-name
and uploadcare--widget__file-size
.
Page
When the dialog is opened, the uploadcare--page
class is added to body
and html
instead of the uploadcare-dialog-opened
class.
Dialog
The dialog now has the uploadcare--dialog
class instead of the uploadcare-dialog
class.
The uploadcare-responsive-panel
class removed, the dialog is responsive by default.
The different dialog states (active
, inactive
)
are now defined within uploadcare--dialog_state_*
class.
Here are the elements that the dialog contains:
uploadcare--dialog__container
(v2:uploadcare-dialog-inner-wrap
),uploadcare--dialog__close
— the button in the top right corner (closes the dialog) (v2:uploadcare-dialog-close
),uploadcare--dialog__panel
— panel,uploadcare--dialog__powered-by
(v2:uploadcare-dialog-footer
).
Panel
The panel is the main block holding the menu, tabs and content.
When you call uploadcare.openPanel
your placeholder is replaced with the panel.
The panel now has the uploadcare--panel
class instead of the uploadcare-dialog-panel
class.
If panel is inside the dialog, it also has the uploadcare--dialog__panel
class.
The panel contains the following elements:
panel__content
,panel__icon
(v2:uploadcare-dialog-icon
),panel__menu
(v2:uploadcare-dialog-tabs
).
If the widget doesn’t have tabs, the panel__menu
element has the panel__menu_hidden
class.
If you turn the multiple
option on,
the panel has the uploadcare--panel_multiple
class (v2: uploadcare-dialog-multiple
)
and contains the following elements:
panel__done
(v2:uploadcare-dialog-source-base-done
),panel__file-counter
(v2:uploadcare-panel-footer-counter
),panel__footer
(v2:uploadcare-panel-footer
),panel__message
(v2:uploadcare-panel-footer-text
),panel__show-files
(v2:uploadcare-dialog-source-base-show-files
).
Menu
The menu now has theuploadcare--menu
class instead of the uploadcare-dialog-tabs
class.
The menu contains the following elements:
uploadcare--menu__toggle
,uploadcare--menu__toggle-icon
,uploadcare--menu__items
,uploadcare--menu__item
(v2:uploadcare-dialog-tab
),uploadcare--menu__icon
.
Tab
The tab now has the uploadcare--tab
class instead of the uploadcare-dialog-tabs-panel
class.
The tab contains the following elements:
uploadcare--tab__header
uploadcare--tab__content
uploadcare--tab__title
uploadcare--tab__footer
uploadcare--tab__action-button
uploadcare--tab__iframe
File
The file now has the uploadcare--file
class instead of the uploadcare-file-item
class.
The different file states are now defined within uploadcare--file_*
class:
error
, uploading
, uploaded
.
The file contains the following elements:
uploadcare--file__description
,uploadcare--file__error
(v2:uploadcare-file-item__error
),uploadcare--file__icon
,uploadcare--file__name
(v2:uploadcare-file-item__name
),uploadcare--file__preview
(v2:uploadcare-file-item__preview
),uploadcare--file__progressbar
(v2:uploadcare-file-item__progressbar
),uploadcare--file__remove
(v2:uploadcare-file-item__remove
),uploadcare--file__size
(v2:uploadcare-file-item__size
).
Others blocks
As it was already mentioned above, we implemented lots of changes into the widget markup. In this article, we described the most significant ones, not all of them. Check out our templates and stylesheets folders for more details. Or, contact our support in case of any specific issues.
Styles
All styles have been rewritten. We use flexbox for layout and PostCSS for post processing. See our stylesheets folder and PostCSS config for more details.
Icons
We quit using PNG files. Instead, we now use SVG sprites inside uploadcare--panel
.
For example, here’s the Facebook icon for the menu:
<svg width="32" height="32" role="presentation" class="uploadcare--icon uploadcare--menu__icon">
<use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#uploadcare--icon-facebook"></use>
</svg>
html
Or, the “Remove” button that appears in the list of files when the multiple option is turned on:
<svg role="presentation" width="32" height="32" class="uploadcare--icon">
<use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#uploadcare--icon-remove"></use>
</svg>
html