Breaking changes ⚠️

We don’t follow SemVer during the beta phase. That means that we may introduce changes that break existing features and functionality. It’s important to pin your version and read the changelog before updating.

Script tag approach

We recommend to use the one of modern code distribution services, such as:

Connect script to your document:

<script src="" type="module"></script>

Then you can use blocks in your application markup.

File uploader example:


Dynamic script connection (types support)

First, install the npm package:

npm i --save-exact @uploadcare/blocks

Then use connectBlocksFrom function to connect blocks:

import { connectBlocksFrom } from '@uploadcare/blocks/abstract/connectBlocksFrom.js';


That's it! Now you can use components for placing into html, like this:


You may need to implement some logic, which depends on connected blocks or get access directly to the imported components. Since connectBlocksFrom returns Promise, place all you need using .then()

import { connectBlocksFrom } from '@uploadcare/blocks/abstract/connectBlocksFrom.js';

const STYLES = '';

  (blocks) => {
    if (!blocks) {
      return; // To avoid errors in SSR case

    // Now you can realize your logic, e.g.:
    const uploader = new blocks.FileUploaderRegular();
    uploader.setAttribute('css-src', STYLES);

Advanced mode

Install the npm package:

npm i @uploadcare/blocks

Then you can use blocks and build your own solutions from the source code:

import * as LR from '@uploadcare/blocks';


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



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



Next step: Configuration ➡️