Skip to main content

​
Quick Start Guide

This guide will help you set up a working file uploader in minutes. By the end, you’ll have a fully functional upload form ready to accept files.

​
Prerequisites

Before you begin, you’ll need:
  1. An Uploadcare account (sign up for free)
  2. Your Public API key from the Uploadcare dashboard
Keep your Public Key accessible - you’ll need it in the next steps. Never commit secret keys to your repository.

​
Installation

First, install File Uploader: 
npm install @uploadcare/file-uploader

​
Basic Setup

Follow these steps to create your first uploader:
1

Import and define components

In your JavaScript file, import File Uploader and define the web components:
import * as UC from '@uploadcare/file-uploader';
import '@uploadcare/file-uploader/index.css';

UC.defineComponents(UC);
The defineComponents() function registers all File Uploader components as custom elements.
2

Add uploader to your HTML

Add the uploader component and configuration to your HTML:
<uc-file-uploader-regular ctx-name="my-uploader"></uc-file-uploader-regular>
<uc-config ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY"></uc-config>
Replace YOUR_PUBLIC_KEY with your actual Public API key from Uploadcare.
The ctx-name attribute links the uploader and config together. Use the same value for both components.
3

Test your uploader

Open your application in a browser. You should see an “Upload files” button. Click it to open the upload dialog and select a file from your device.

​
Complete Example

Here’s a complete working example: 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>File Uploader Demo</title>
  <link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@1/web/uc-file-uploader-regular.min.css"
  />
</head>
<body>
  <uc-file-uploader-regular ctx-name="my-uploader"></uc-file-uploader-regular>
  <uc-config ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY"></uc-config>

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

​
Using the Inline Uploader

For a different layout, try the inline uploader that’s always visible on the page: 
<uc-file-uploader-inline ctx-name="my-uploader"></uc-file-uploader-inline>
<uc-config ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY"></uc-config>

​
Handling Upload Events

To handle uploaded files, listen for events using the Upload Context Provider: 
<uc-file-uploader-regular ctx-name="my-uploader"></uc-file-uploader-regular>
<uc-config ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY"></uc-config>
<uc-upload-ctx-provider ctx-name="my-uploader"></uc-upload-ctx-provider>

const uploadCtxProvider = document.querySelector('uc-upload-ctx-provider');

uploadCtxProvider.addEventListener('change', (event) => {
  const { successEntries } = event.detail;
  
  successEntries.forEach((entry) => {
    console.log('File uploaded:', entry);
    console.log('CDN URL:', entry.cdnUrl);
    console.log('UUID:', entry.uuid);
  });
});
The change event fires whenever the upload state changes. Use successEntries to access successfully uploaded files.

​
Common Configuration Options

Customize your uploader with configuration attributes:

​
Multiple Files

<uc-config 
  ctx-name="my-uploader" 
  pubkey="YOUR_PUBLIC_KEY"
  multiple="true"
  multiple-max="10"
></uc-config>

​
Images Only

<uc-config 
  ctx-name="my-uploader" 
  pubkey="YOUR_PUBLIC_KEY"
  img-only="true"
></uc-config>

​
File Size Limit

<uc-config 
  ctx-name="my-uploader" 
  pubkey="YOUR_PUBLIC_KEY"
  max-local-file-size-bytes="10485760"
></uc-config>

​
Specific File Types

<uc-config 
  ctx-name="my-uploader" 
  pubkey="YOUR_PUBLIC_KEY"
  accept="image/*, .pdf, .doc, .docx"
></uc-config>

​
Custom Upload Sources

<uc-config 
  ctx-name="my-uploader" 
  pubkey="YOUR_PUBLIC_KEY"
  source-list="local, url, camera, dropbox, gdrive"
></uc-config>
Available sources: local, url, camera, dropbox, gdrive, gphotos, instagram, facebook, onedrive, box, vk, evernote, flickr, huddle

​
Getting File Information

When a file is successfully uploaded, you receive an OutputFileEntry object with comprehensive information: 
{
  status: 'success',
  uuid: 'a7d9f5e8-3b1c-4a2e-9f8d-1c5e7b9a3d4f',
  cdnUrl: 'https://ucarecdn.com/a7d9f5e8-3b1c-4a2e-9f8d-1c5e7b9a3d4f/',
  name: 'my-image.jpg',
  size: 204800,
  isImage: true,
  mimeType: 'image/jpeg',
  uploadProgress: 100,
  fileInfo: { /* full Uploadcare file info */ },
  // ... more properties
}
Key properties:
  • uuid - Unique file identifier
  • cdnUrl - Direct URL to access the file
  • name - Original filename
  • size - File size in bytes
  • fileInfo - Complete file metadata from Uploadcare API

​
Using Uploaded Files

Once uploaded, use the cdnUrl to display or download files:

​
Display an Image

uploadCtxProvider.addEventListener('change', (event) => {
  const { successEntries } = event.detail;
  
  successEntries.forEach((entry) => {
    if (entry.isImage) {
      const img = document.createElement('img');
      img.src = entry.cdnUrl;
      document.body.appendChild(img);
    }
  });
});

​
Apply Image Transformations

Uploadcare provides URL-based image transformations: 
// Resize to 800x600
const resizedUrl = `${entry.cdnUrl}-/resize/800x600/`;

// Crop to 400x400 center
const croppedUrl = `${entry.cdnUrl}-/crop/400x400/center/`;

// Convert to WebP
const webpUrl = `${entry.cdnUrl}-/format/webp/`;

// Chain transformations
const transformedUrl = `${entry.cdnUrl}-/resize/800x/-/quality/smart/-/format/auto/`;

​
Debugging

Enable debug mode to see detailed logs in the console: 
<uc-config 
  ctx-name="my-uploader" 
  pubkey="YOUR_PUBLIC_KEY"
  debug="true"
></uc-config>
Debug mode logs configuration changes, upload progress, and error details. Disable it in production.

​
Troubleshooting

​
Components Not Rendering

Make sure you’ve called defineComponents() before the HTML is parsed: 
import * as UC from '@uploadcare/file-uploader';
UC.defineComponents(UC);

​
CSS Not Loading

Import the CSS file in your JavaScript: 
import '@uploadcare/file-uploader/index.css';
Or add it to your HTML: 
<link rel="stylesheet" href="path/to/node_modules/@uploadcare/file-uploader/dist/index.css">

​
“Invalid public key” Error

Verify your public key:
  1. Check for typos in the pubkey attribute
  2. Ensure you’re using the Public Key, not the Secret Key
  3. Confirm the key is from the correct Uploadcare project

​
CORS Errors

Uploadcare handles CORS automatically. If you see CORS errors, check:
  1. You’re using a valid public key
  2. Your domain is not blocked in Uploadcare project settings

​
Next Steps

Now that you have a working uploader, explore more features:

Configuration

Explore all configuration options

Customization

Customize the appearance

Events

Handle upload events

Validation

Add file validation rules

Build docs developers (and LLMs) love

Get started for freeTalk to us