Configuration

This page is about the new configuration approach. Want to migrate from legacy CSS configuration to lr-config? Check out our migration guide

The configuration settings for the File Uploader should be provided via the lr-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.

Ensure that the validation rules for the uploader align with the validation rules specified in your project settings.

Basic configuration

<lr-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"
>
</lr-config>

<lr-file-uploader-regular
  css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@{{__BLOCKS_VERSION__}}/web/lr-file-uploader-regular.min.css"
  ctx-name="my-uploader"
></lr-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 for more details.

Required attributes

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:

<lr-file-uploader-regular ctx-name="MY_CONTEXT"></lr-file-uploader-regular>

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

Shadow styles `css-src`

To ensure a visually appealing uploader, including the CSS file is necessary. We employ shadow DOM to encapsulate styles, therefore, for each type of uploader, 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
`lr-file-uploader-regular`	`lr-file-uploader-regular.min.js`	`lr-file-uploader-regular.min.css`
`lr-file-uploader-inline`	`lr-file-uploader-inline.min.js`	`lr-file-uploader-inline.min.css`
`lr-file-uploader-minimal`	`lr-file-uploader-inline.min.js`	`lr-file-uploader-minimal.min.css`
`lr-cloud-image-editor`	`lr-cloud-image-editor.min.js`	`lr-cloud-image-editor.min.css`

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

<script type="module">
  import * as LR from "https://cdn.jsdelivr.net/npm/@uploadcare/blocks@{{__BLOCKS_VERSION__}}/web/lr-file-uploader-regular.min.js";
  LR.registerBlocks(LR);
</script>

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

<lr-file-uploader-regular
  ctx-name="my-uploader"
  css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@{{__BLOCKS_VERSION__}}/web/lr-file-uploader-regular.min.css"
></lr-file-uploader-regular>

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, see How to import CSS directly from NPM package for more details.

The css-src attribute is required for all solution blocks within the page. However, for blocks that do not have their own styles, this attribute is not necessary.

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.

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

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

true means true (e.g. <lr-config this-is-boolean="true"></lr-config>)
attribute presence means true (e.g. <lr-config this-is-boolean></lr-config>).
empty string mean true (e.g. <lr-config this-is-boolean=""></lr-config>).
any other thruthy value means true (e.g. <lr-config this-is-boolean="value"></lr-config>).
false means false (e.g. <lr-config this-is-boolean="false"></lr-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:

const config = document.querySelector('lr-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 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 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.