Advanced customization: build your own uploading flow

If our pre-built uploader solution isn't enough for you, meet our highly customizable blocks.

Blocks list

🍰 Concept description

There are so many use cases and many workflows for file uploading. Is it possible to create an uploading solution to fit them all?

We believe it is — with the power of Custom Elements standard and our widget-purpose-specific open-source Symbiote.js library.

You can use high-level, simple HTML and CSS to customize layouts and define the most popular scenarios. You can create your own blocks from scratch with JavaScript using BlockComponent base-class.

Key features

🏠 Integration basics

We use the Custom Elements standard to make integration seamless.

That allows us to use simple HTML code to define layouts and place our widgets into other templates or other markups. Custom Elements are compatible with most modern technologies and provide a consistent workflow. Please, check out the list of high-level tests passed with a set of modern frontend frameworks and libraries: Custom Elements Everywhere

We also provide a set of reference integrations.

🚀 Create your own file uploader

The standard flow of the uploading widget creation is following:

  1. Install lr-blocks package: npm i @uploadcare/blocks.
  2. Create the set of all components you need.
import * as LR from '@uploadcare/blocks';


class Uploader extends LR.FileUploaderRegular {}
  1. Create your widget class with desired layout.
import * as LR from '@uploadcare/blocks';


class Uploader extends LR.FileUploaderRegular {}
  1. Create CSS configuration file.
@import url('@uploadcare/blocks/blocks/themes/lr-basic/index.css');
  1. Place resulting custom HTML-tag into your application markup and connect CSS.

As you can see, that's quite simple.

You should get a Public API key in Uploadcare project's dashboard to use file uploading features.

🎨 Customize everything!

First, please look at our CSS approach discussion. Please don't hesitate to take part; your opinion is very important to us.

Look & feel

Each block has a reference CSS file located in a directory and a JavaScript class definition module. You can use it as the template to create your own custom styling (or CSS animations) for any library block. All blocks and their children act like regular DOM elements; therefore, you can use native CSS selectors and any existing styling approach. All significant component states are provided as element attribute flags, so you can use the full power of CSS to customize the blocks deeply.

Lear more about CSS theme creation.

Layout & composition

Block components can be used separately or in combinations. You can combine them to create a common workflow like this one:


<lr-modal strokes>
    <lr-drop-area with-icon clickable></lr-drop-area>
    <lr-source-list wrap></lr-source-list>


Block templates

You can quickly override any block template by setting the new template property value to any block class. Here is an example:

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

LR.ProgressBarCommon.template = /* HTML */ `
  <h1>My custom heading</h1>
  <div class="my-custom-class">My custom template</div>

All elements created by blocks are discoverable via developer tools in your browser. It's easy to find out what exactly you should edit to achieve the proper result. You don't need to install any specific tool to do that.

Custom blocks

You can create your own custom blocks to handle some specific use cases. You need to use the Block JavaScript base class to do that.

⚙️ More in depth

💬 Discussions

If you have questions, ideas, usage feedback, or would like to suggest any other topic, feel free to join our GitHub Discussions!

⚠️ Issues

Found a problem? Create an issue.