UploadingFile Uploader

Migration guide for @uploadcare/file-uploader v1.29.0

In v1.29.0, @uploadcare/file-uploader introduces the Plugin API — a system that replaces hardcoded activity components (camera, URL, external sources, cloud image editor) with a modular, extensible plugin architecture.

What stays the same

All documented public API remains unchanged, including:

  • Solution component tags (uc-file-uploader-regular, uc-file-uploader-minimal, uc-file-uploader-inline)
  • CSS custom properties for theming
  • Configuration options
  • Documented events and public methods
  • Public TypeScript types exposed by the package

If you use File Uploader only through CSS custom properties and documented config options, no migration steps should be required.

Breaking changes

Source button attribute: type replaced with data-source-id

The uc-source-btn component no longer uses the type HTML attribute. If you target source buttons with CSS attribute selectors, update them:

1/* Before */
2uc-source-btn[type="local"] {
3  /* ... */
4}
5
6/* After */
7uc-source-btn[data-source-id="local"] {
8  /* ... */
9}

Edit button on file items: .uc-edit-btn replaced with .uc-plugin-action-btn

The hardcoded edit button in file items has been replaced by a plugin-driven system. If you target the edit button with CSS, update the selector:

1/* Before */
2.uc-edit-btn {
3  /* ... */
4}
5
6/* After */
7.uc-plugin-action-btn[data-plugin-action-id="edit-file"] {
8  /* ... */
9}

CSS cascade layers: new uc.shared layer

A new CSS cascade layer uc.shared has been added between uc.base and uc.components:

1/* Before */
2@layer uc, uc.base, uc.components, uc.rules, uc.solutions, uc.post-reset;
3
4/* After */
5@layer uc, uc.base, uc.shared, uc.components, uc.rules, uc.solutions, uc.post-reset;

This only affects you if you use CSS Layers and import .layered.css files (e.g., uc-file-uploader-regular.layered.min.css). Several internal component styles (modal, icons, progress bars, spinners, etc.) moved from uc.components to uc.shared. If you override internal styles at a specific cascade level, verify your overrides still apply correctly.

Hardcoded activity modals replaced with uc-plugin-activity-renderer

If you build custom solutions (not using the provided uc-file-uploader-regular, uc-file-uploader-minimal, or uc-file-uploader-inline) and embed activity modals directly in your templates, you must replace them:

1<!-- Before -->
2<uc-modal id="camera" strokes block-body-scrolling>
3  <uc-camera-source></uc-camera-source>
4</uc-modal>
5<uc-modal id="url" strokes block-body-scrolling>
6  <uc-url-source></uc-url-source>
7</uc-modal>
8<uc-modal id="external" strokes block-body-scrolling>
9  <uc-external-source></uc-external-source>
10</uc-modal>
11<uc-modal id="cloud-image-edit" strokes block-body-scrolling>
12  <uc-cloud-image-editor-activity></uc-cloud-image-editor-activity>
13</uc-modal>
14
15<!-- After -->
16<uc-plugin-activity-renderer mode="modal"></uc-plugin-activity-renderer>

The mode attribute controls how plugin activities are displayed:

  • mode="modal" — activities open in modal dialogs. Use this for regular and minimal solutions where activities overlay the main UI.
  • mode="inline" — activities render inline within the component. Use this for inline solutions where activities are displayed in place.

This does not affect you if you use the provided solution components (uc-file-uploader-regular, etc.) — they already include the plugin activity renderer with the correct mode.

Need help?

If you were relying on an internal or undocumented API and can’t migrate without it, please open an issue with a minimal reproduction and your customization goal (what you’re trying to achieve).