> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server.

# Uploadcare jQuery File Uploader

> Learn how to work with jQuery File Uploader. It installs with just two lines of code, and is provided as a typical JavaScript library.

> **Warning**
>
> **Warning:** jQuery File Uploader package is officially deprecated as of **September 1, 2025**.\
>
> Moving forward, we will no longer release updates or new versions of this widget.\
>
> Support will also be discontinued, except in cases where critical security vulnerabilities need to be addressed.\
> \
>
> If you're using jQuery File Uploader in your project, we recommend considering our [web-component-based File Uploader](/docs/file-uploader/), which contains all the latest features and updates.\
> \
>
> We understand that this might affect your workflows, and we are committed to providing as much support as possible during this transition.
> If you have any questions or concerns, please reach out to [our support](mailto:help@uploadcare.com)

Uploadcare jQuery File Uploader is responsive and mobile-ready HTML5 widget
that allows users to select and upload multiple files from various sources.
Also, it includes an in-browser image editor. You can customize the appearance
and functionality to match your website and task.

jQuery File Uploader is supplied as a JavaScript library. It overrides an `<input type="file">`
control on an HTML page with a button that opens up the uploading widget dialog.
Like this:

## Features \[#features]

jQuery File Uploader helps you perform the following tasks:

* Uploading
  * [Add a file uploading](/docs/uploads/file-uploader/#install) capability to your website or
    app.
  * Upload files of any type and up to 5 TB in size.
  * Get files from various upload sources, including local storage, camera,
    social media, and cloud storage services.
  * Upload multiple files in one go.
  * Track upload jobs with an individual progress bar for each file.
  * Speed up the uploading with the uploading network (it works like CDN).
* Image Handling
  * Show image previews.
  * Implement custom image [crop options](/docs/uploads/file-uploader/#crop-option).
  * Edit, enhance, and apply photo filters to images in any browser with the
    [image editor](/docs/uploads/image-editor/).
* Validation
  * [Validate files](/docs/uploads/validation/) by their format or size.
  * Validate files by their [MIME type](/docs/moderation/#file-types) (server-side filtering).
  * [Automatically resize large incoming images](#client-side-image-resize).
* Security
  * Make your uploading system compatible with SOC 2, HIPAA, and more via [security settings](/docs/uploads/content-security-policy/).
  * Prevent remote code execution through File Uploading.
  * Prevent code execution in uploaded files like `SVG`, `html` and `xml`.
* Reliability
  * All your uploads go to the storage covered by SLA with a 99.9% uptime.

### Supported browsers \[#browsers]

jQuery File Uploader works in all modern browsers, desktop and
mobile. Here's a list of supported browsers:

| Desktop      | Mobile                |
| ------------ | --------------------- |
| Chrome: 37+  | Android Browser: 4.4+ |
| Firefox: 32+ | Opera Mobile: 8+      |
| Safari: 9+   | iOS Safari: 9+        |
| Edge: 12+    | IE Mobile: 11+        |
| IE: 10+      | Opera Mini: Last      |

jQuery File Uploader will most probably run in older browser versions as well.
More on [browser version support](https://github.com/uploadcare/uploadcare-widget#browser-support).

## Installation \[#install]

Select either option to install jQuery File Uploader:

* [Global installation](#cdn)
* [NPM](#npm)

Refer to [no-code integrations](/docs/integrations/) to use the uploading widget with your
website platform like Shopify, etc.

Before proceeding with your install, check out the [dependencies](#dependencies)
and jQuery File Uploader [bundles](#bundles) below.

### Dependencies

jQuery File Uploader doesn't have any external dependencies except for jQuery.
Generally, the uploading widget comes in two versions: with and without embedded jQuery library.

For example, you can use jQuery commands on the page if you included [a bundle](#bundles)
with jQuery:

```js
var $ = uploadcare.jQuery;
$('body').append('It works!');
```

### Bundles

Depending on your project, you can select a specific JS library bundle:

* [`uploadcare.full.js`](https://ucarecdn.com/libs/widget/3.x/uploadcare.full.js): a full bundle with built-in jQuery.
* [`uploadcare.js`](https://ucarecdn.com/libs/widget/3.x/uploadcare.js): a default bundle without jQuery.
* [`uploadcare.api.js`](https://ucarecdn.com/libs/widget/3.x/uploadcare.api.js): a bundle without uploading widget UI and jQuery [JavaScript API](/docs/file-uploader-api/) only.
* [`uploadcare.lang.en.js`](https://ucarecdn.com/libs/widget/3.x/uploadcare.lang.en.js): a bundle without jQuery, `en` locale only.

Include a minified bundle version by adding `.min` before `.js`.

By default, minified (and without jQuery) `uploadcare.min.js` is exported to NPM
and other package managers.

### Global installation \[#cdn]

Get [your public API key](/docs/start/settings/#keys-public) and
include this into the `<head>`:

This package is deprecated and no longer maintained. Do not use it for new integrations. Install `@uploadcare/file-uploader` instead, see [installation](/docs/file-uploader/installation/).

Note: If you already use jQuery, you can use the [alternative bundle](#bundles)
that comes without jQuery, so you won't download it twice.

Now you can use the Uploader:

```html
<input type="hidden" role="uploadcare-uploader" name="my_file_input" />
```

### NPM

This package is deprecated. For new integrations, install `@uploadcare/file-uploader` instead, see [installation](/docs/file-uploader/installation/).

You can get the widget instance and configure it with configuration object:

This widget instantiation example is deprecated. For new integrations, install `@uploadcare/file-uploader` instead, see [installation](/docs/file-uploader/installation/).

## Configure

Set of features, such as upload sources, image editing tools, can be customized
via the [widget options](/docs/uploads/file-uploader-options/).

You can have mixed settings for different widget instances.
Global variables will affect all File Uploader instances, and local attributes will override global settings.

Here's how you can configure jQuery File Uploader:

* [Global variables](#global-variables), initialized on page load.
* [Local attributes](#local-attributes), initialized when a new widget
  instance is created.
* [The `settings` object](#settings-object).

### Global variables

Globals are specified as global JavaScript variables in your `<script>` tag.
For example:

This global-variable configuration is for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

### Local attributes

Local options are specified in the target `<input>` tag as `data-*` attributes.
For example:

When setting boolean options locally in HTML tag attributes, any value or no
value is considered as `true`:

To disable a local option, use either:

These local-attribute configuration examples are for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

### Settings object

Most of the widget options can also be set within the `settings` object.
See the [jQuery File Uploader API reference](/docs/file-uploader-api/widget/) for more details.
For example:

This settings-object example is for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

## Upload sources

jQuery File Uploader supports more than a dozen of upload sources, including local
file storage, web camera; external URL; cloud services, and social networks.
In UI, the sources are shown as tabs.

The set of enabled upload sources is controlled via the `data-tabs`
[option](/docs/uploads/file-uploader-options/#option-tabs).

### List of supported upload sources \[#upload-source-list]

| Code       | File Source                                 | Default |
| ---------- | ------------------------------------------- | ------- |
| `file`     | Local disk                                  | **On**  |
| `camera`   | Local webcam                                | **On**  |
| `url`      | Any URL                                     | **On**  |
| `facebook` | [Facebook](https://facebook.com)            | **On**  |
| `gdrive`   | [Google Drive](https://drive.google.com)    | **On**  |
| `gphotos`  | [Google Photos](https://photos.google.com/) | **On**  |
| `dropbox`  | [Dropbox](https://www.dropbox.com)          | **On**  |
| `onedrive` | [OneDrive](https://onedrive.live.com)       | **On**  |
| `box`      | [Box](http://www.box.com/)                  | **Off** |

### Configuring upload sources \[#configure-upload-sources]

You can configure the set of upload sources globally or per jQuery File Uploader
instance. The global parameter is called `UPLOADCARE_TABS`. Locally you can
utilize the `data-tabs` attribute.

In both cases, you'll pass a space-separated string with tab names.

Configuring the set of sources globally:

Configuring the list of sources locally:

These upload-source configuration examples are for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

### Custom tabs

<svg width="0" height="0">
  <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" />
</svg>

You can add custom tabs into your widget. These tabs can be additional
upload sources or whatever you design them to be. For example, display all
uploaded files.

* [Registering a new tab](#register)
* [Making the custom tab work](#code)
* [Adjusting the look](#tab-look)
* [Example](#example)

#### Registering a new tab \[#register]

Register a new tab via the `registerTab` method.

This custom-tab registration example is for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

#### Coding tab's actions \[#code]

Once the tab is registered, write a custom code. The following code will display
uploaded images made with this widget instance. It'll pass a list of file
UUIDs with the `settings` [object](/docs/uploads/file-uploader/#settings-object). When a user
selects a file for uploading, the file info can be passed to the dialog using
`dialogApi`.

This custom-tab implementation example is for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

#### Adjusting the look \[#tab-look]

Customize your custom tab's look via CSS. Use `<svg>` and `<symbol>` elements:

These custom-tab styling examples are for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

#### Custom tab in action \[#example]

Here's a live example of jQuery File Uploader with the custom tab we've just created.
It displays images uploaded with this the uploading widget instance:

## Multiple file uploading \[#multiple-files]

jQuery File Uploader allows you to upload multiple files in one go. Each
file will have its tiny progress bar and a preview when it's uploaded.

![Uploading multiple files with individual progress bars](https://examples.ucarecd.net/93ddea11-3e73-4a49-9f78-b56f0dad63b9/-/preview/)

The uploading widget will display individual errors if some files couldn't be uploaded
(e.g., due to size or format validation failure) and it won't affect the rest of
the upload.

### Enable batch uploading

Enable batch file uploading with [the `data-multiple` attribute](/docs/uploads/file-uploader-options/#option-multiple)
in the widget `<input>` element.

This batch-uploading configuration is for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

Check out multiple file uploading:

Multiple file uploads are collected as [file groups](/docs/file-groups/) with
respective `group_id` as opposed to single file UUIDs.

## Automatically resize uploaded images \[#client-side-image-resize]

jQuery File Uploader lets you accept hi-res images and
shrink them in size to a reasonable resolution, keeping the original aspect
ratio.

Benefits of automatic image resize on upload:

* Users don't need to downscale images on their devices to meet the uploading
  requirements.
* Optimized storage.
* Faster uploading.

Use the `data-image-shrink` [option](/docs/uploads/file-uploader-options/#option-image-shrink) to apply
client-side image resize with values like:

* `800x600`, shrinks images to 0.48 megapixels with the default JPEG quality of
  80% (default, when not set).
* `1600x1600 95%`, shrinks images to 2.5 megapixels with the JPEG quality set to
  95%.

### Specs and limits

The output resolution limit for `data-image-shrink` is 268 MP (e.g., `16384x16384`).
It conforms to the maximum resolution that WebKit desktop browsers support.
We recommend not to use values greater than 16.7 MP (`4096x4096`),
because it's a current limit for iOS devices.

Uploaded images won't be shrunk in the following cases:

* When a client browser doesn't support a specified output resolution.
* For images uploaded from [social media and URLs](/docs/uploads/file-uploader/#upload-sources).
* If the `original resolution` is less than 2x larger than the `target resolution`.
  For example, it won't shrink a 2560x1560px (4 MP) image to 1600x1600px (2.5
  MP). It will work if you had a 2448x3264px (8 MP) input image. This
  limitation preserves an optimal image quality and file size balance.
* If the image color mode is CMYK.

The output format will be JPEG by default unless your input image has an alpha
channel (transparency). In this case, PNG will be used instead.
Grayscale images will be converted to RGB.

EXIF and ICC profile info is copied as-is and includes an original image
orientation, camera model, geolocation, and other settings of an original image.

### Resize to 1 MP on a client side: \[#examples]

### Resize multiple files to 0.4 MP on a client side:

These client-side image-resize examples are for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

## Localization

jQuery File Uploader is highly customizable and
implements UI localization and custom pluralization rules. With
&#x20;locales, you can make your app instantly adapt to user
languages.

There currently are:

You can either [set an existing locale](/docs/uploads/file-uploader-options/#option-locale) or add a
custom one along with its pluralization rules.

### Adding a locale \[#add-locale]

You can add your localization, if there's no one yet, by forking the main
[jQuery File Uploader repo](https://github.com/uploadcare/uploadcare-widget) and adding a new localization file to
[this list](https://github.com/uploadcare/uploadcare-widget/blob/master/src/locales).

Another option is overriding specific locale items in your global uploading widget configuration:

This locale-override example is for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

The default is [an English locale](https://github.com/uploadcare/uploadcare-widget/blob/master/src/locales/en.js). If a string
item is missing in a locale you created or customized, English will be a
fallback.

Uploading errors can also be redefined in the locale.
You can see [errors reference](https://github.com/uploadcare/uploadcare-widget/blob/064213bc38030c5c69ba62ad1e0e7741e6f328be/src/locales/en.js#L161).

### Pluralization rules \[#pluralization]

Pluralization rules may vary in different languages. In the English locale,
there'll be `"1 file"`, but `"3 files"`. This rule is described under the
`file:` key in the locale file.

Strings with quantitative values are based on what a pluralization function
returns. You'll pass a number into a function, and it'll output a subkey
related to your input.

There are two subkeys for the English localization: `one` and the `other`.
However, it can get more complex with other languages. For example, take a look
at the `file:` subkeys for the [Russian locale](https://github.com/uploadcare/uploadcare-widget/blob/master/src/locales/ru.js#L25-L27).
The `%1` sequence is used to format numbers into pluralized strings.

Each locale we provide with jQuery File Uploader is supplied with its Unicode-based
[pluralization rules](http://cldr.unicode.org/). If you wish to override those,
you can define a custom pluralization function and assign it to the
[`UPLOADCARE_LOCALE_PLURALIZE`](/docs/uploads/file-uploader-options/#option-locale-pluralize) variable.

The following setting makes the widget use the message under the `some`
subkey for input numbers from 2 to 10:

These pluralization examples are for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

## Styling

jQuery File Uploader can be easily integrated into your
product and match your website look or a web app's UI.

### Styling With CSS \[#widget-styles]

jQuery File Uploader is thoroughly annotated with CSS classes.
It's your starting point into deeper customization. You can find a class for
every widget item by inspecting its elements or sifting through jQuery File
Uploader [source code](https://github.com/uploadcare/uploadcare-widget/tree/master/src/stylesheets/blocks/widget).

The uploading widget dialog window look can be customized via the
`uploadcare--dialog` class.

### Changing uploader button color \[#color-buttons]

Changing the button color is one of the most common cases:

### Button shadow

You can add shadow and experiment with fonts and colors:

### Uploading circle color

You can display the file uploading progress. The fill color can be changed via
the CSS `color` property, while `border-color` will work for your background.

Here, you can test the widget with a customized uploading circle:

### Custom progress bar

You can replace the built-in progress bar. To do that, you need to add a
listener to the current widget instance and get it in the `onChange`
callback. It'll be a file object for the regular widget or a group object
for multiple widgets. After that, listen to the `progress` event and
change your progress bar according to the current `uploadProgress`.

The following `installProgressBar` function does all that. It receives the two
arguments: the widget instance and a progress bar DOM element. Everything
else runs on CSS, animation included.

### Uploaded image preview

The default jQuery File Uploader behavior is to show an image preview when a user
selects an image. You might want to embed this preview on your page somewhere
around the widget button. Such a preview could be more informative than
simply displaying file names and sizes.

Note, you have full control over the size and position of your embed. Just use
CSS.

Image preview for a multi-file widget may look differently:

You can change the displayed images or rearrange the existing ones; all changes
will then be reflected in the thumbnail list.

### jQuery File Uploader embed

User experience means the world to us. Therefore, we provide a lot of
customization options that cover both jQuery File Uploader appearance and behavior.

The look of jQuery File Uploader can be changed [via CSS](/docs/uploads/file-uploader/#styling),
is a great starting point for controlling your widget behavior.

Another thing you can do is to embed jQuery File Uploader as a panel as opposed to
a default dialog window.

#### Embed jQuery File Uploader using panel \[#panel]

By default, the widget dialog appears on a button click. The dialog will
appear in a lightbox, which overlays your page's content and dims the
background.

However, you might want to show the widget interface right away. This
appearance is named `panel`.

This panel-embed example is for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

The snippet above replaces your DOM element with the `uploadcare-placeholder` ID
and puts it in place once a user selects a file. This can be used to indicate
the uploading process. Also, the panel can be closed by simply selecting a file.

#### Panel styling

Similar to jQuery File Uploader dialog, the panel can be customized.

The appearance of your embed can be changed [via CSS](/docs/uploads/file-uploader/#styling). In
this example, we remove a sharp border:

This panel-styling example targets deprecated jQuery-based Widget API class names. For new integrations, use `@uploadcare/file-uploader` instead.

Some dialog elements are rendered as `iframe` by Uploadcare servers, which
doesn't let you customize CSS. However, we provide a set of [specific methods](/docs/file-uploader-api/tabs-styling/)
to inject CSS into iframes.

## Image crop \[#crop-option]

Cropping images is one of the most common tasks, so we added it right in the
[jQuery File Uploader](/docs/uploads/file-uploader/) UI.

jQuery File Uploader features a good bunch of crop options, including free
crop. Adding the feature to your widget instance is done by implementing
the `data-crop` [option](/docs/uploads/file-uploader-options/#option-crop).

Note that it'll add an additional step of image editing.

### How cropping works \[#how-it-works]

Technically, image cropping works as post-processing via the
[Image processing feature](https://uploadcare.com/cdn/image-processing/):

* Original images go to an Uploadcare project associated with a
  [Public Key](/docs/start/settings/#keys-public) set as your widget instance.
* The crop is applied as the [`crop`](/docs/transformations/image/resize-crop/#operation-crop) image
  processing operation by injecting its URL directive into original URLs.
* The widget returns resulting CDN URLs with an injected `crop`.

### Configuring crop \[#crop-config]

Crop options are held inside the `data-crop` attribute as a comma-separated
string with presets names. When you define several presets, users will be able
to choose from the related crop options right in the UI.

Each crop preset is a combination of a size or ratio definition and an optional
keyword:

* `"disabled"`, crop is disabled. It can't be combined with other presets.
* `""` or `"free"`, crop is enabled. Users can freely select any crop area on
  their images.
* `"2:3"`, any area with the aspect ratio of 2:3 can be selected for cropping.
* `"300x200"`: same as above, but if the selected area is greater than 300x200
  pixels, the resulting image will be downscaled to fit the dimensions.
* `"300x200 upscale"`: same as above, but even if the selected area is smaller,
  the resulting image gets upscaled to fit the dimensions.
* `"300x200 minimum"`: users won't be able to define an area smaller than
  300x200 pixels. If an image we apply the crop to is smaller than 300x200
  pixels, it will be upscaled to fit the dimensions.

## Default files in the widget dialog \[#predefined-files]

jQuery File Uploader allows you to make specified
files appear in jQuery File Uploader dialog on open.

Specify these files by adding the `value` attribute to your widget
`<input>` element. The attribute may either be empty or hold a file CDN URL.

If you set the `value` externally and trigger the DOM change event, it affects the widget.
For instance, setting it to a file UUID or a CDN URL will result in that the file being loaded into jQuery File Uploader.
You can apply it anytime, and it'll take effect immediately.

Here's how you do it:

```html
<input type="hidden" role="uploadcare-uploader" name="my_file"
  data-public-key="YOUR_PUBLIC_KEY"
  value="https://examples.ucarecd.net/05da8fb8-bbe9-4da1-a79c-eaf5979152db/"
/>
```

## Show image previews in jQuery File Uploader \[#image-previews]

After uploading, the uploading widget loads image previews from the CDN:

```
-> (GET) https://{subdomain}.ucarecd.net/{uuid}/
```

With this feature turned on, the uploading widget can't show previews because signed URLs
include a token part. To work that around, load images through a
[signing proxy](/docs/security/secure-delivery/#use-with-file-uploader), where your backend can add the token:

```
-> (GET) https://domain.com/preview?url=https%3A%2F%2Fcdn.domain.com%2F{uuid}%2F
-> (Redirect) https://cdn.domain.com/{uuid}/?token=exp={timestamp}~acl={acl}~hmac={digest}
```

Here are two options that can help you show image previews:

* [`previewProxy`](/docs/uploads/file-uploader-options/#option-preview-proxy). It routes preview requests through your signing proxy.
* [`previewUrlCallback`](/docs/uploads/file-uploader-options/#option-preview-url-callback). It works if
  you need to send extra data like [JWT tokens](https://jwt.io/).

### Option `previewProxy` \[#preview-proxy]

Implementing the `previewProxy` option works best for these cases:

* Your application uses cookie-based authentication.
* Your signing proxy and your app are located in the same domain
  (otherwise, cookies won't be sent).
* You don't need any other image-related data beside URLs.

To use `previewProxy` option, specify your signing proxy endpoint URL, and
you're good to go:

It'll let the uploading widget load image previews via the following URL:

```
https://domain.com/preview?url=https%3A%2F%2Fcdn.domain.com%2F{uuid}%2F
```

It appends a query parameter with image preview URL to `previewProxy`:

By default, the uploader uses `url` as the query parameter name, but you
can have a custom naming as well:

These `previewProxy` configuration examples are for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

### Option `previewUrlCallback` \[#preview-url-callback]

This option provides you with explicit control over the uploading widget preview
URLs. In code, `previewUrlCallback` is a function with a signature:

Example:

These `previewUrlCallback` configuration examples are for the deprecated jQuery-based Widget API. For new integrations, use `@uploadcare/file-uploader` instead.

Note, `previewUrlCallback` overrides `previewProxy`, and the latter option will
be ignored.

## JS snippets and CSS tricks \[#js-snippets]

In this cookbook part, you can find popular code examples and resolutions of
common tasks when working with jQuery File Uploader. Less words, more code!

This cookbook section contains recipes for the deprecated jQuery-based Widget API. For current integrations, use @uploadcare/file-uploader instead.

### Versioning \[#versioning-uploader]

When we introduce backward-incompatible changes, we release new major versions.
Once published, such versions are supported for *2 years*.
You will still be able to use any file uploader version after its support term at your own risk.

| Version                                                    | Date Published | Supported Until |
| ---------------------------------------------------------- | -------------- | --------------- |
| [File Uploader (1.x)](/docs/file-uploader/)                | 5 Aug 2024     | TBD             |
| File Uploader (0.x)                                        | 18 May 2023    | 5 Aug 2024      |
| [jQuery File Uploader (3.x)](/docs/uploads/file-uploader/) | 28 Jun 2017    | 17 Oct 2022     |
| 2.x                                                        | 20 Feb 2015    | 1 Jan 2020      |
| 1.x                                                        | 21 Mar 2014    | 1 Jun 2019      |
| 0.x                                                        | 6 Sep 2012     | 1 Jun 2019      |