https://github.com/alijahanpak/handy-uploader
Handy Uploader is a responsive Vue.js file uploader and file viewer with an image compressor. It offers three display options (simple / thumbnail / table).
https://github.com/alijahanpak/handy-uploader
component compressor file fileuploader nuxt vue vuecli vuetify
Last synced: 5 months ago
JSON representation
Handy Uploader is a responsive Vue.js file uploader and file viewer with an image compressor. It offers three display options (simple / thumbnail / table).
- Host: GitHub
- URL: https://github.com/alijahanpak/handy-uploader
- Owner: alijahanpak
- License: mit
- Created: 2020-06-26T22:06:23.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2026-01-17T18:27:15.000Z (5 months ago)
- Last Synced: 2026-01-18T02:41:23.620Z (5 months ago)
- Topics: component, compressor, file, fileuploader, nuxt, vue, vuecli, vuetify
- Language: TypeScript
- Homepage:
- Size: 2.12 MB
- Stars: 70
- Watchers: 2
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Handy Uploader
[](https://badge.fury.io/js/handy-uploader)
[](https://opensource.org/licenses/MIT)
[](https://vuejs.org/)
[](https://www.typescriptlang.org/)
## 🚀 [Live Demo](https://illustrious-griffin-257b43.netlify.app)
A comprehensive Vue 3 file uploader component library with advanced features including **automatic video thumbnail generation**, multiple upload styles, and extensive file type support.
## ✨ Key Features
### 🎥 **Video Thumbnail Generation**
- **Automatic thumbnail extraction** from video files using Canvas API
- Support for **MP4, AVI, MOV, WMV, FLV, WebM** formats
- Real-time thumbnail display with play button overlay
- No external dependencies required
### 📁 **Comprehensive File Support**
- **Images**: JPG, JPEG, PNG, GIF, BMP, SVG, WebP, TIFF
- **Videos**: MP4, AVI, MOV, WMV, FLV, WebM
- **Documents**: PDF, DOC, DOCX, TXT, RTF, ODT
- **Spreadsheets**: XLS, XLSX, CSV, ODS
- **Presentations**: PPT, PPTX, ODP
- **Archives**: ZIP, RAR, 7Z, TAR, GZ
- **Audio**: MP3, WAV, FLAC, AAC, OGG
### 🎨 **Multiple Upload Styles**
- **ThumbnailUploader**: Grid-based layout with file previews
- **TableUploader**: Table-based layout for detailed file information
- **SimpleUploader**: Minimalist drag-and-drop interface
### 🌍 **Internationalization**
- **8 languages**: English, Chinese, Spanish, French, German, Japanese, Korean, Arabic
- RTL support for Arabic
- Easy language switching
## 📦 Installation
```bash
npm install handy-uploader
```
```bash
yarn add handy-uploader
```
```bash
pnpm add handy-uploader
```
## 🚀 Quick Start
### 1. Install Dependencies
Make sure you have the required peer dependencies:
```bash
npm install vue@^3.0.0 vuetify@^3.0.0
```
### 2. Import and Use
```vue
import { ThumbnailUploader } from 'handy-uploader'
import type { FileData } from 'handy-uploader'
const handleFilesSelected = (files: FileData[]) => {
console.log('Selected files:', files)
// Each file includes base64 data and video thumbnails are auto-generated
}
```
### 3. Setup Vuetify (Required)
```typescript
// main.ts
import { createApp } from 'vue'
import { createVuetify } from 'vuetify'
import 'vuetify/styles'
import '@mdi/font/css/materialdesignicons.css'
const vuetify = createVuetify()
const app = createApp(App)
app.use(vuetify)
app.mount('#app')
```
## 📖 Component Usage
### ThumbnailUploader (Recommended)
Perfect for media files with automatic video thumbnail generation:
```vue
import { ThumbnailUploader } from 'handy-uploader'
const onFilesSelected = (files) => {
// Video files will have thumbnails automatically generated
files.forEach(file => {
if (file.type === 'video') {
console.log('Video thumbnail:', file.thumbnail) // Base64 thumbnail
}
})
}
```
### TableUploader
Great for document management with detailed file information:
```vue
```
### SimpleUploader
Minimal drag-and-drop interface:
```vue
```
## ⚙️ API Reference
### Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `maxFileSize` | `number` | `10485760` | Maximum file size in bytes (10MB) |
| `maxFileCount` | `number` | `5` | Maximum number of files |
| `acceptedFileTypes` | `string[]` | `['*']` | Accepted MIME types |
| `language` | `string` | `'en'` | Language code |
| `theme` | `string` | `'light'` | Theme variant |
### Events
| Event | Payload | Description |
|-------|---------|-------------|
| `files-selected` | `FileData[]` | Emitted when files are selected |
| `file-removed` | `FileData` | Emitted when a file is removed |
| `error` | `Error` | Emitted on errors |
### FileData Interface
```typescript
interface FileData {
id: string
name: string
size: number
type: string
format: string
base64?: string
thumbnail?: string // Auto-generated for videos
lastModified: number
}
```
## 🎯 Advanced Features
### Video Thumbnail Generation
The library automatically generates thumbnails for video files:
```javascript
// Thumbnails are generated automatically
const videoFile = {
name: 'video.mp4',
type: 'video',
thumbnail: 'data:image/jpeg;base64,/9j/4AAQ...' // Auto-generated
}
```
### File Type Detection
Automatic file type detection and icon assignment:
```javascript
// Automatic type detection
const file = {
name: 'document.pdf',
type: 'document', // Auto-detected
icon: 'mdi-file-pdf-box', // Auto-assigned
color: 'red' // Auto-assigned
}
```
### Image Compression
Built-in image compression for large files:
```vue
```
## 🌍 Internationalization
Supported languages:
```javascript
const languages = [
'en', // English
'zh', // Chinese
'es', // Spanish
'fr', // French
'de', // German
'ja', // Japanese
'ko', // Korean
'ar' // Arabic (RTL)
]
```
## 🛠️ Technical Requirements
### Peer Dependencies
- **Vue**: ^3.0.0
- **Vuetify**: ^3.0.0
### Browser Support
- Chrome 88+
- Firefox 85+
- Safari 14+
- Edge 88+
### Bundle Size
- **Gzipped**: ~45KB
- **Minified**: ~120KB
## 🎨 Customization
### Theming
Works with Vuetify's theming system:
```javascript
// vuetify.config.js
export default createVuetify({
theme: {
themes: {
light: {
primary: '#1976D2',
secondary: '#424242',
// Custom theme colors
}
}
}
})
```
### Custom Styling
```vue
.handy-uploader {
--uploader-border-radius: 12px;
--uploader-primary-color: #1976D2;
--uploader-background: #f5f5f5;
}
```
## 📝 Examples
### Complete Example with All Features
```vue
File Upload with Video Thumbnails
Selected Files:
![Thumbnail]()
{{ file.name }} ({{ formatFileSize(file.size) }})
import { ref } from 'vue'
import { ThumbnailUploader, type FileData } from 'handy-uploader'
const selectedFiles = ref<FileData[]>([])
const currentLanguage = ref('en')
const isDark = ref(false)
const handleFilesSelected = (files: FileData[]) => {
selectedFiles.value = files
console.log('Files with thumbnails:', files)
}
const handleFileRemoved = (file: FileData) => {
console.log('File removed:', file.name)
}
const handleError = (error: Error) => {
console.error('Upload error:', error)
}
const formatFileSize = (bytes: number) => {
return bytes > 1024 * 1024
? `${(bytes / 1024 / 1024).toFixed(2)} MB`
: `${(bytes / 1024).toFixed(2)} KB`
}
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- [GitHub Repository](https://github.com/alijahanpak/vue-file-uploader)
- [npm Package](https://www.npmjs.com/package/handy-uploader)
- [Documentation](https://github.com/alijahanpak/vue-file-uploader#readme)
- [Issues](https://github.com/alijahanpak/vue-file-uploader/issues)
## 📊 Stats
---
**Made with ❤️ for the Vue.js community**