File Uploader API

Data output

We provide the dedicated element for the data output purposes — <lr-data-output>. This Custom Element can be connected to some workflow context and provide you with convenient data access. Place this element inside an uploader tag:

<lr-file-uploader-regular class="config" css-src="./blocks/themes/lr-basic/index.css">
  <lr-data-output use-console use-input use-group use-event></lr-data-output>
</lr-file-uploader-regular>html

Let's walk through its attributes:

  • use-console — enables browser console output without modifying the source code.
  • use-event — enables custom events (data-output) dispatching for the DOM element. These events contain all uploading data and can be processed at any level of your application.
  • use-group — create a group from uploaded files, the same as --cfg-group-output.
  • use-template — uploading results could be rendered as a list of nested DOM elements. You can specify a simple template for that.
  • use-input — create input to be used inside HTML-form.
  • input-name — used together with use-form. Sets the input name. The context name will be used by default.
  • input-required — whether the input is required or not. Works as the native required attribute.

Then, use event listener to get all data:

const dataOutput = document.querySelector('lr-data-output');
dataOutput.addEventListener('lr-data-output', (e) => {
  console.log(e.detail);
});javascript

Context provider

For convenience, we provide the <lr-upload-ctx-provider> tag, which offers additional methods for managing an uploader. Simply place the context provider tag inside a file uploader tag.

  <lr-file-uploader-inline
    css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.22.8/web/file-uploader-inline.min.css"
    class="uploader-cfg"
    ctx-name='my-uploader'
    id="uploader"
  >
    <lr-upload-ctx-provider ctx-name='my-uploader' id="uploaderctx"></lr-upload-ctx-provider>
</lr-file-uploader-inline>html

To access the context provider element and utilize its methods, simply retrieve it as follows:

const uploaderCtx = document.querySelector('#uploaderctx');javascript

Set upload metadata

setUploadMetadata(metadata: Record<string, string>) => void

This method allows you to set arbitrary metadata for all files that will be uploaded after calling the method.

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

Update context CSS data

updateCtxCssData() => void

This method applies a new configuration to all blocks that are associated with a common context. Read more how to dynamically change the uploader's configuration.

uploaderCtx.updateCtxCssData();javascript

Naming convention

By design, all custom elements should have a dash symbol (-) in their names. All custom tags used in uploader are prefixed with the lr- part.

Examples:

...
<lr-icon></lr-icon>
...
<lr-button></lr-button>
...
<lr-whatever></lr-whatever>
...html

To exclude naming collisions, use the other prefixes for your own custom elements.

Examples:

...
<my-own-icon></my-own-icon>
...
<my-own-button></my-own-button>
...
<my-own-whatever></my-own-whatever>
...html