@samluvanda/uploadx/README.md

Modern, lightweight, and extensible JavaScript file uploader supporting chunked uploads, filtering, retry logic, progress tracking, and event hooks.

# UploadX

**UploadX** is a modern, configurable, HTML5-powered JavaScript file uploader library. It supports chunked uploads, customizable filters, progress tracking, and more — all in a lightweight and extensible package.

![badge](https://img.shields.io/badge/uploadx-lightweight-blue)

---


## 🚀 Features

- ✅ **Modern JavaScript (ES6+)**
- 🔄 **Chunked Upload Support** — break large files into smaller chunks for better reliability
- 🔌 **Configurable & Extensible** — customize filters, events, headers, size limits, retry logic, and more
- 🧠 **Smart Queue Management** — automatic progress, retries, and clean error handling
- 🎯 **HTML5 File API** — no legacy code or Flash dependencies
- 🔊 **Rich Event System** — hook into all stages of the upload process

---


## 📦 Installation

```bash
npm install @samluvanda/uploadx
```

---


## ✍️ Usage

```js
import { Uploader } from 'uploadx';

const uploader = new Uploader({
  browse_button: 'browseBtn',
  url: '/upload',
  filters: {
    mime_types: [{ title: 'Images', extensions: 'jpg,jpeg,png,gif' }],
    max_file_size: '5mb',
    prevent_duplicates: true
  },
  chunk_size: '1mb',
  max_retries: 3,
  multi_selection: true,
});

uploader.bind('FileUploaded', (up, file, response) => {
  console.log(`Uploaded: ${file.name}`, response);
});

document.getElementById('startBtn').onclick = () => uploader.start();
```

---


## 📁 Documentation

See [docs/DOCUMENTATION.md](docs/DOCUMENTATION.md)

---


## 🤝 Contributing

We welcome PRs, issues, and enhancements. Please read our [contributing guide](docs/CONTRIBUTING.md).

---


## 🫣 Sponsor This Project

If UploadX made your life easier, consider [sponsoring me on GitHub](https://github.com/sponsors/samluvanda). I promise not to use the funds on things like... more coffee ☕ (okay, maybe just a little).

---


## 🌐 Third-Party Upload Handlers

Several third-party handlers for UploadX exist and may be useful for integration with different backend platforms.  
**Please note:** These are external community projects. The UploadX project does not maintain or endorse them.

- **Laravel:** [uploadx-laravel](https://github.com/samluvanda/uploadx-laravel)

Want to contribute your own handler? Open a pull request to list it here.

---


## 🧪 Browser Compatibility

UploadX uses the HTML5 File API and is compatible with all major modern browsers.

---


## 📄 License

MIT © 2025 [Samson Luvanda](mailto:s_luvanda@hotmail.com)