Installation
On this page
From CDN
We recommend using the one of the modern code distribution services, such as:
Inserting the following code into the <head>
section of your HTML document:
<script src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.6/web/blocks.min.js" type="module"></script>
html
or import it directly into your JavaScript code:
<script type="module">
import * as LR from "https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.6/web/blocks.min.js";
LR.registerBlocks(LR);
</script>
html
Note that we distribute the library as ES modules, so you need to use the type="module"
attribute on the <script>
tag.
We're also providing IIFE bundle, but it's not recommended to use it directly.
<script src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.6/web/blocks.iife.min.js" async></script>
<script>
LR.registerBlocks(LR);
</script>
html
From NPM
Install the npm package:
npm i --save-exact @uploadcare/blocks
sh
- ⚠️ 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.
Then you can use the File Uploader and build your own solutions from the source code:
import * as LR from '@uploadcare/blocks'
LR.registerBlocks(LR)
javascript
Dynamic script connection
There is an alternative way if your project meets the following criteria:
- Does not support new language features (such as nullish coalescing operator, static class properties) — for instance, this might apply to projects built with frameworks such as Nuxt 2. (Note that Nuxt 3 supports modern JavaScript features and works as needed).
- Has SSR and does not support node conditional exports.
Then you can use this workaround to import the uploader only at the browser runtime, bypassing your project's build system and obtaining a working type system. This can be achieved without the need to manually configure the build process (using tools such as Babel) or disabling SSR for a specific package.
First, install the npm package:
npm i --save-exact @uploadcare/blocks
sh
Then import connectBlocksFrom
function to connect the library dynamically and
avoid errors:
import { connectBlocksFrom } from '@uploadcare/blocks/abstract/connectBlocksFrom.js';
connectBlocksFrom('https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.6/web/blocks.iife.min.js');
javascript
You may need to implement some logic that depends on connected uploader or get
access directly to the imported components. Since connectBlocksFrom
returns
Promise
, use .then()
import { connectBlocksFrom } from '@uploadcare/blocks/abstract/connectBlocksFrom.js';
const STYLES = 'https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.6/web/lr-file-uploader-regular.min.css';
connectBlocksFrom('https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.6/web/blocks.iife.min.js').then(
(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);
document.body.appendChild(uploader);
}
);
javascript
Choose a solution
To use the File Uploader in your application markup, select the tag that best fits your needs from the table below and place it in your HTML document:
Mode | Syntax |
---|---|
Regular mode | <lr-file-uploader-regular> </lr-file-uploader-regular> |
Inline mode | <lr-file-uploader-inline> </lr-file-uploader-inline> |
Minimal mode | <lr-file-uploader-minimal> </lr-file-uploader-minimal> |
Look at the File Uploader solutions for more.
Example,
<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@0.25.6/web/lr-file-uploader-regular.min.css"
></lr-file-uploader-regular>
html
The <lr-config>
block is used to configure the uploader. Take a look at
uploader configuration.
The ctx-name
attribute is used to specify the name of the uploader context,
which allows wire blocks together. Required.
The css-src
attribute is used to specify the URL of the basic CSS styles for
the uploader. Required.
How to import CSS directly from NPM package
If you have installed the @uploadcare/blocks
from NPM, you can import CSS directly
from the package instead of using CDN. But you need to configure your bundler to resolve URL path to CSS file.
With Vite, it's possible using the Explicit URL Imports feature out of the box:
import fileUploaderRegularCssSrc from '@uploadcare/blocks/web/lr-file-uploader-regular.min.css?url'
<lr-config ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY"></lr-config>
<lr-file-uploader-regular
ctx-name="my-uploader"
css-src={fileUploaderRegularCssSrc}
></lr-file-uploader-regular>
jsx
With Webpack 5, it's possible using the Asset Modules. Here is an example of the webpack config:
{
module: {
rules: [
{
resourceQuery: /url/,
type: 'asset/resource',
},
]
},
}
javascript
Then you can use ?url
resource query to import CSS:
import fileUploaderRegularCssSrc from '@uploadcare/blocks/web/lr-file-uploader-regular.min.css?url'
<lr-config ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY"></lr-config>
<lr-file-uploader-regular
ctx-name="my-uploader"
css-src={fileUploaderRegularCssSrc}
></lr-file-uploader-regular>
jsx