@scaleflex/uploader

Framework-agnostic file upload Web Component for Scaleflex VXP.
Drag & drop, URL, webcam, screen capture, and cloud providers — in a single HTML tag.

Live Demo | Documentation | Examples | CDN | npm | Scaleflex

---

Features

• Drag & drop — animated drop zone with visual feedback, plus paste from clipboard
• Multiple sources — device, URL import, webcam, screen capture, and 7 cloud providers (Google Drive, Dropbox, OneDrive, Box, Instagram, Facebook, Unsplash)
• Concurrent uploads — configurable concurrency with retry and exponential backoff
• Real-time progress — per-file and aggregate progress with speed and ETA
• File restrictions — type, size, and count limits with clear rejection reasons
• Modal or inline — use as a modal overlay or embed directly in your page, with configurable header buttons (close, back, or none) for wizard and step flows
• Internationalisation — built-in i18n via i18next; pass locale in config ('fr', 'de', 'en-US', etc.) — falls back to English for untranslated keys
• Fully themeable — CSS custom properties with --sfx-up-* prefix
• React wrapper — controlled open prop and imperative ref via @scaleflex/uploader/react
• Lit 3 — lightweight Web Component with Shadow DOM encapsulation
• ESM + CJS — dual build, tree-shakeable, TypeScript declarations included

Installation

npm install @scaleflex/uploader

Or use the CDN for a no-bundler setup:

https://cdn.scaleflex.com/uploader/1.8.5/sfx-uploader.min.js

<script src="https://cdn.scaleflex.com/uploader/1.8.5/sfx-uploader.min.js"></script>

Quick start

Web Component

<script type="module">
  import '@scaleflex/uploader/define';

  const uploader = document.querySelector('sfx-uploader');
  uploader.config = {
    auth: {
      mode: 'security-template',
      container: 'YOUR_CONTAINER',
      securityTemplateId: 'SECU_...',
    },
    locale: 'fr', // optional — defaults to navigator.language
  };
  uploader.open();
</script>

<sfx-uploader></sfx-uploader>

React

import { useState } from 'react';
import { Uploader } from '@scaleflex/uploader/react';

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Upload files</button>
      <Uploader
        open={open}
        config={{
          auth: {
            mode: 'security-template',
            container: 'YOUR_CONTAINER',
            securityTemplateId: 'SECU_...',
          },
          locale: 'fr', // optional — defaults to navigator.language
        }}
        onClose={() => setOpen(false)}
        onAllComplete={(ok, failed) => console.log('Done', ok, failed)}
        // Fires per dropped/picked folder as each one finishes — useful for
        // incrementally refreshing an asset/folder tree without waiting for
        // the whole batch. Root-level files don't trigger this.
        onFolderComplete={(folder, ok) => refreshFolder(folder, ok)}
      />
    </>
  );
}

Sizing

The uploader modal and the bulk metadata editor expose CSS custom properties so hosts can make them larger (or smaller) without forking styles.

Variable	Default	Affects
--sfx-up-modal-max-width	1100px	Main uploader modal max width
--sfx-up-max-height	88vh	Main uploader modal height
--sfx-up-content-max-width	1600px	Inner content max width
--sfx-up-bulk-modal-width	980px	Bulk metadata edit modal width
--sfx-up-bulk-modal-height	82vh	Bulk metadata edit modal height

Example — enlarge both modals:

sfx-uploader {
  --sfx-up-modal-max-width: 1400px;
  --sfx-up-max-height: 92vh;
  --sfx-up-bulk-modal-width: 1280px;
  --sfx-up-bulk-modal-height: 88vh;
}

The bulk modal still clamps to calc(100vw - 40px) / calc(100vh - 40px) so it never overflows the viewport.

Package exports

Specifier	Description
@scaleflex/uploader	Core SfxUploader class (use with customElements.define)
@scaleflex/uploader/define	Auto-registers <sfx-uploader> — import for side-effect
@scaleflex/uploader/react	React wrapper component

Browser support

Browser	Version
Chrome / Edge	90+
Firefox	100+
Safari	15.4+

Claude Code Integration

If you use Claude Code, this package ships with a ready-made skill that helps Claude add the uploader to your project — detecting your framework, wiring auth, events, theming, and restrictions automatically.

Per-project (recommended — share with your team via version control):

mkdir -p .claude/skills/integrate-uploader
cp node_modules/@scaleflex/uploader/.claude/skills/integrate-uploader/SKILL.md \
   .claude/skills/integrate-uploader/SKILL.md

Commit the .claude/skills/ directory to version control. The skill is now available to everyone on the team.

Per-user (available across all your projects):

mkdir -p ~/.claude/skills/integrate-uploader
cp node_modules/@scaleflex/uploader/.claude/skills/integrate-uploader/SKILL.md \
   ~/.claude/skills/integrate-uploader/SKILL.md

Then type /integrate-uploader in Claude Code and it will walk you through the full integration — install, config, events, and theming — tailored to your stack (React, Vue, vanilla JS, etc.).

Documentation

See the full documentation and interactive examples at scaleflex.github.io/uploader.

License

See LICENSE.