> 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.

# File Uploader configuration

> File Uploader settings allow you to customize params through uc-config block.

The configuration settings for the File Uploader should be provided via the `uc-config` block.
This block accepts both attributes and DOM properties.

Refer to the list of pre-defined parameters that are used by default in the [repository](https://github.com/uploadcare/file-uploader/blob/main/blocks/Config/initialConfig.js).

Ensure that the validation rules for the uploader align with the validation rules
specified in your [project settings](https://app.uploadcare.com/projects/-/settings/).

## Basic configuration

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.css">

<uc-config
  ctx-name="my-uploader"
  pubkey="YOUR_PUBLIC_KEY"
  img-only="true"
  multiple="true"
  max-local-file-size-bytes="524288000"
  use-cloud-image-editor="true"
  source-list="local, url, camera, dropbox"
>
</uc-config>

<uc-file-uploader-regular
  ctx-name="my-uploader"
></uc-file-uploader-regular>
```

Define the rules that the file uploader should adhere to, and ensure that you include your public key.
Refer to the complete list of available [options](/docs/file-uploader/options/) for more details.

## Required attributes

### Context `ctx-name` \[#context-ctx-name]

Context serves as a bridge connecting different custom elements (referred to as "blocks") on a page.
It enables these blocks to share a common state and interact with each other.
Additionally, it facilitates the division of multiple uploaders on a single page.

To bind one block to another, you should manually set a context using the ctx-name attribute:

```html
<uc-file-uploader-regular ctx-name="MY_CONTEXT"></uc-file-uploader-regular>
```

The `ctx-name` attribute is required for all blocks, even if there's only one block on the page.

### Styles \[#styles]

To ensure a visually appealing uploader, including the CSS file is necessary.
We employ global styles, therefore, for each [type of uploader](/docs/file-uploader/#solutions),
the corresponding CSS file should be included separately.

Each solution has its own dedicated CSS file. Here is a table indicating the specific CSS files for each solution:

| Tag                        | JS file                           | CSS file                           |
| -------------------------- | --------------------------------- | ---------------------------------- |
| `uc-file-uploader-regular` | `uc-file-uploader-regular.min.js` | `uc-file-uploader-regular.min.css` |
| `uc-file-uploader-inline`  | `uc-file-uploader-inline.min.js`  | `uc-file-uploader-inline.min.css`  |
| `uc-file-uploader-minimal` | `uc-file-uploader-inline.min.js`  | `uc-file-uploader-minimal.min.css` |
| `uc-cloud-image-editor`    | `uc-cloud-image-editor.min.js`    | `uc-cloud-image-editor.min.css`    |

Here is an example of including CSS file for `uc-file-uploader-regular`:

```html

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.css">

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

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

<uc-file-uploader-regular
  ctx-name="my-uploader"
></uc-file-uploader-regular>
```

#### [File Uploader basic configuration example](https://codesandbox.io/s/docs-basic-configuration-4dkf8s)

View in CodeSandbox

You aren't restricted to use jsdeliver CDN. You can use any CDN or host the files yourself.
Or even use a bundler to handle CSS file as a static asset, for example:

```js
import "@uploadcare/file-uploader/web/uc-file-uploader-regular.min.css";
import * as UC from "@uploadcare/file-uploader/web/uc-file-uploader-regular.min.js";

UC.defineComponents(UC);
```

## How to define attributes

Given that HTML attribute values are always strings, only simple data types can be passed,
such as strings, numbers, and boolean values.

```html
<uc-config
  this-is-string="I am a string"
  this-is-number="1000"
  this-is-boolean="true"
>
</uc-config>
```

Passing strings and numbers is pretty straightforward. Boolean values are
checked by the following rules:

* `true` means `true` (e.g. `<uc-config this-is-boolean="true"></uc-config>`)
* attribute presence means `true` (e.g.
  `<uc-config this-is-boolean></uc-config>`).
* empty string mean `true` (e.g. `<uc-config this-is-boolean=""></uc-config>`).
* any other thruthy value means `true` (e.g.
  `<uc-config this-is-boolean="value"></uc-config>`).
* `false` means `false` (e.g. `<uc-config this-is-boolean="false"></uc-config>`).

Attributes could be defined in both `kebab-case` and `camelCase`.

## How to define DOM properties

Since HTML attribute values are always strings, you can't pass complex data like
objects or functions. To pass such data, you can use DOM properties. Plain data
also works with DOM properties.

Here is an example of passing an object and function in vanilla JS:

```js
const config = document.querySelector('uc-config')

config.metadata = {
  myCustomData: 'myValue'
}

config.metadata = () => ({
  myCustomData: 'myValue'
})
```

DOM properties could be defined in `camelCase` only.

### Frameworks

If you're using a framework, you can set DOM properties in a framework-specific
way.

For example, in Vue 3, you can use native binding syntax; it will work out of the
box. See [Vue and Web Components](https://vuejs.org/guide/extras/web-components.html#using-custom-elements-in-vue) for
more details.

With React, you can use `ref` to get a reference to the element and set DOM
properties on it. The native binding syntax will be supported in React 19. See
[RFC: Plan for custom element attributes/properties in React 19](https://github.com/facebook/react/issues/11347)
for more details.

## Reactivity

Both attributes and DOM properties are reactive. It means that if you change the
value of an attribute or DOM property, the uploader will be updated
automatically.