File Uploader installation

From CDN

We recommend using one of the modern code distribution services, such as:

• https://jsdelivr.com/
• https://esm.sh/
• https://skypack.dev/
• etc

Import the File Uploader library into your JavaScript code:

1
<script type="module">
2
  import * as UC from 'https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/file-uploader.min.js';
3
  UC.defineComponents(UC);
4
</script>

Note that we distribute the library as ES modules, so you need to use the type="module" attribute on the <script> tag.

We’re also providing IIFE bundle, but it’s not recommended to use it directly.

1
<script
2
  src="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/file-uploader.iife.min.js"
3
  async
4
></script>
5
<script>
6
  UC.defineComponents(UC);
7
</script>

From NPM

Install the npm package:

1
npm i @uploadcare/file-uploader

Then register the File Uploader components for usage:

1
import * as UC from '@uploadcare/file-uploader';
2
3
UC.defineComponents(UC);

React Uploader

This library allows you to easily integrate the File Uploader into your React applications:

1
npm i @uploadcare/react-uploader

Framework examples

Ready-to-run examples are available in our examples repository:

• All examples (GitHub)
• JavaScript
• React (Web Components)
• React (adapter)
• Vue
• Angular
• Svelte
• Next.js (Web Components)
• Next.js (adapter)

For setup paths by framework, see framework integrations.

Dynamic script connection

There is an alternative way if your project meets the following criteria:

• Does not support new language features (such as nullish coalescing operator, static class properties) — for instance, this might apply to projects built with frameworks such as Nuxt 2. (Note that Nuxt 3 supports modern JavaScript features and works as needed).
• Has SSR and does not support node conditional exports.

Then you can use this workaround to import the uploader only at the browser runtime, bypassing your project’s build system and obtaining a working type system. This can be achieved without the need to manually configure the build process (using tools such as Babel) or disabling SSR for a specific package.

First, install the npm package:

1
npm i @uploadcare/file-uploader

Then import loadFileUploaderFrom function to connect the library dynamically and avoid errors:

1
import { loadFileUploaderFrom } from '@uploadcare/file-uploader/abstract/loadFileUploaderFrom.js';
2
3
loadFileUploaderFrom(
4
  'https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/file-uploader.iife.min.js',
5
);

You may need to implement some logic that depends on connected uploader or get access directly to the imported components. Since loadFileUploaderFrom returns Promise, use .then()

1
import { loadFileUploaderFrom } from '@uploadcare/file-uploader/abstract/loadFileUploaderFrom.js';
2
3
loadFileUploaderFrom(
4
  'https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/file-uploader.iife.min.js',
5
).then((UC) => {
6
  if (!UC) {
7
    return; // To avoid errors in SSR case
8
  }
9
10
  // Now you can realize your logic, e.g.:
11
  const uploader = new UC.FileUploaderRegular();
12
  document.body.appendChild(uploader);
13
});

Choose a solution

To use the File Uploader in your application markup, select the tag that best fits your needs from the table below and place it in your HTML document:

Look at the File Uploader solutions for more.

Example:

1
<link
2
  rel="stylesheet"
3
  href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.css"
4
/>
5
6
<uc-config ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY"></uc-config>
7
8
<uc-file-uploader-regular ctx-name="my-uploader"></uc-file-uploader-regular>

The <uc-config> block is used to configure the uploader. Take a look at uploader configuration.

The ctx-name attribute is used to specify the name of the uploader context, which allows blocks to be wired together. Required.

Dynamic mode

The dynamic-button attribute can be used with the Regular File Uploader to replace the default static upload button with a compact, state-aware control. It shows configured upload sources, accepts drag and drop, and changes after files are selected, uploaded, or failed.

1
<uc-config
2
  ctx-name="my-uploader"
3
  pubkey="YOUR_PUBLIC_KEY"
4
  source-list="local, camera, url"
5
  dynamic-button-view-mode="auto"
6
></uc-config>
7
8
<uc-file-uploader-regular ctx-name="my-uploader" dynamic-button></uc-file-uploader-regular>

See Dynamic button for view modes, behavior, and use cases.

Headless mode

The headless attribute can be used with the Regular File Uploader to hide the default upload button. This is useful when you want to replace the default button with your own custom UI element and trigger the upload flow programmatically.

When headless mode is enabled, use the initFlow() method to start the upload process:

1
<link
2
  rel="stylesheet"
3
  href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.css"
4
/>
5
6
<uc-config ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY"></uc-config>
7
8
<uc-upload-ctx-provider id="uploaderctx" ctx-name="my-uploader"></uc-upload-ctx-provider>
9
10
<uc-file-uploader-regular ctx-name="my-uploader" headless></uc-file-uploader-regular>
11
12
<button id="custom-upload-btn">Upload Files</button>
13
14
<script type="module">
15
  import * as UC from 'https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/file-uploader.min.js';
16
  UC.defineComponents(UC);
17
18
  // Optional but safe: wait until the provider element is defined
19
  await customElements.whenDefined('uc-upload-ctx-provider');
20
21
  const ctx = document.querySelector('#uploaderctx');
22
  const button = document.getElementById('custom-upload-btn');
23
24
  const api = ctx.getAPI();
25
  button.addEventListener('click', () => api.initFlow()); // initFlow(): void
26
</script>

Note:
All examples assume you have configured your API keys. Replace YOUR_PUBLIC_KEY with your actual public key, or set it via environment variables. The component must be defined before calling initFlow().