Configuration

All settings for the File Uploader should be provided in CSS. It could be CSS files or CSS rules are defined somewhere in your project. Tune everything: validation rules, appearance, texts, icons, and layouts. You can redefine styling or any other setting using a custom CSS file.

Look the list of pre-defined parameters used by default in the repository.

Rules:

  • The variable value should be a correct JSON value.
  • Strings should be taken in quotes.
  • We use the 1 or 0 numbers to define boolean flags.

Any configuration value can be defined and redefined at any level of the DOM tree regarding CSS selector specificity.

Be sure that validation rules of an uploader are the same as validation rules in your project settings.

Basic configuration

<lr-file-uploader-regular
  css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.22.8/web/file-uploader-regular.min.css"
  class="my-config"
></lr-file-uploader-regular>html

Define the rules that the file uploader should follow, and don't forget to include your public key. Look the full list of available options.

.my-config {
  --cfg-pubkey: "yourpublickey";
  --cfg-img-only: 1;
  --cfg-multiple: 1;
  --cfg-max-local-file-size-bytes: 524288000;
  --cfg-use-cloud-image-editor: 1;
  --cfg-source-list: "local, url, camera, dropbox";
  --darkmode: 0;
  --h-accent: 223;
  --s-accent: 100%;
  --l-accent: 61%;
}css

Dynamic configuration

Via style property

We handle style property updates automatically. You can update your configuration in the following way:

let uploader = document.querySelector('lr-file-uploader-regular');
uploader.style.setProperty('--cfg-source-list', 'local, url');javascript

Via class property

If you want to switch the whole configuration CSS class, you need to call the method updateCtxCssData() explicitly.

.config-1 {
  --cfg-source-list: 'local, url';
}
.config-2 {
  --cfg-source-list: 'local, camera';
}css
<lr-file-uploader-regular ctx-name='my-uploader' class="lr-wgt-common config-1">
  <lr-upload-ctx-provider ctx-name='my-uploader'></lr-upload-ctx-provider>
</lr-file-uploader-regular>html
let uploader = document.querySelector('lr-file-uploader-regular');
let uploaderCtx = document.querySelector('lr-upload-ctx-provider');

uploader.classList.replace('config-1', 'config-2');
uploaderCtx.updateCtxCssData();javascript

To update the configuration for all blocks in the same context, you can use the updateCtxCssData method of the context provider. Please note that it is necessary to use updateCtxCssData() after any configuration update.

Arbitrary metadata

Metadata is additional key-value data that you can attach to a file during the upload process. For example, you could store a unique file identifier from your application.

Please never store any sensitive data in metadata.

Use the setUploadMetadata method from the context provider to set metadata for all files that will be uploaded:

uploaderCtx.setUploadMetadata({ foo: 'bar' });javascript

Read more about arbitrary file metadata.

Context

Context helps connect different custom elements ("blocks") on a page, allowing them to share a common state and interact with each other. You can set a context manually to bind one block to another using ctx-name attribute:

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