ngx-image-upload

🚀 A feature-rich Angular image upload component with preview, validation, automatic compression, zoom capabilities, and full form integration.

✨ Features

• 📷 Image Upload & Preview with drag-and-drop support
• 🔍 Interactive Preview Modal with zoom/pan capabilities
• ✅ Comprehensive Validation (file type, size, required)
• 📉 Automatic Image Compression before upload (configurable)
• 🎨 Customizable UI with CSS Variables and templates
• 📱 Responsive Design with adjustable dimensions
• ♿ Accessibility First (ARIA labels, keyboard navigation)
• 📦 Standalone Component with zero dependencies
• ⚡ Smooth Animations & loading states

🚀 Installation

npm install @osmanabd/ngx-image-upload-preview

📌 Basic Usage

import { ImageUploadComponent } from '@osmanabd/ngx-image-upload-preview';

Reactive Forms Example

<form [formGroup]="profileForm" (ngSubmit)="onSubmit()">
  <ngx-image-upload 
    formControlName="avatar"
    [required]="true"
    [maxSizeMB]="5"
    [compress]="true"
    [compressionOptions]="{ maxSizeMB: 1, maxWidthOrHeight: 1024, initialQuality: 0.8 }"
    [allowedTypes]="['image/jpeg', 'image/png', 'image/webp']"
    previewTitle="Profile Preview"
    requiredMessage="Please upload a profile photo"
    (fileSelected)="handleFile($event)">
  </ngx-image-upload>
  
  <button type="submit">Save Profile</button>
</form>

Template-driven Forms Example

<ngx-image-upload
  [(ngModel)]="user.avatar"
  name="avatar"
  [compress]="true"
  [compressionOptions]="{ maxSizeMB: 1 }"
  [defaultImage]="'assets/default-avatar.png'">
</ngx-image-upload>

📉 Image Compression

To reduce file size and optimize uploads, ngx-image-upload supports automatic client-side image compression.

🔧 Compression Options

| Input | Type | Default | Description | |--------------------|----------|---------|-----------------------------------------------------------------------------| | compress | boolean | false | Enable/disable image compression before upload | | compressionOptions | object | {} | Compression settings (see below) |

Example Options

compressionOptions = {
  maxSizeMB: 1,             // Target size in MB
  maxWidthOrHeight: 1024,   // Resize image to max width or height
  initialQuality: 0.8       // Quality for JPEG/WebP compression
}

📱 Images taken from iPhones or modern phones (2–5MB) can be reduced to 500KB–1MB depending on resolution and quality.

🖼️ Unsupported formats (e.g., HEIC, SVG) are auto-converted to JPEG before compression.

🔍 Preview Modal Features

The interactive preview modal includes:

• Zoom In/Out controls (0.5x - 5x)
• Drag-to-Pan functionality when zoomed
• Reset to Default view
• Fullscreen Overlay with blurred backdrop

🎨 Customization

ngx-image-upload {
  --primary-color: #4a90e2;
  --error-color: #ff4757;
  --border-radius: 8px;
  --background-color: #f8f9fa;
  --text-color: #2d3436;
  --box-shadow: 0 2px 15px rgba(0,0,0,0.1);
  --transition-speed: 0.3s;
}

✅ Validation & Error Handling

Built-in Validations:

<ngx-image-upload
  [maxSizeMB]="5"
  [allowedTypes]="['image/jpeg', 'image/png']"
  requiredMessage="Image is required">
</ngx-image-upload>

Validation Scenarios

1. Required Validation – Displays custom message when no image is selected
2. File Size Validation – Max size in MB (after compression if enabled)
3. MIME Type Validation – JPEG, PNG, WebP (wildcards not supported yet)
4. Custom Error Messages – For localization or branding

📋 API Reference

Inputs

| Input | Type | Default | Description | |---------------------|----------|--------------|--------------------------------------| | requiredMessage | string | - | Marks field as required with provided message | | maxSizeMB | number | 2 | Maximum file size in megabytes | | allowedTypes | string[] | ['image/jpeg', 'image/png'] | Allowed MIME types | | previewTitle | string | - | Title shown in preview modal | | showPreviewButton | boolean | true | Toggle preview zoom button | | enablePreviewModal| boolean | true | Enable/disable fullscreen preview | | defaultImage | string | - | Fallback image for errors | | previewButtonLabel| string | "View full size" | Preview Button Label | | width | number | 150 | Preview container width | | height | number | 150 | Preview container height | | src | string | - | Default preview image | | disabled | boolean | false | Disable/Enable input | | compress | boolean | false | Enable automatic image compression | | compressionOptions| object | {} | Options to configure compression |

Outputs

| Output | Type | Description | |---------------------|---------|-----------------------| | fileSelected | File | Emits selected file after validation & compression |

♿ Accessibility Features

• ARIA Labels for all interactive elements
• Focus States for visual feedback
• Screen Reader optimized:
  • Live error announcements
  • Modal interaction labels
  • Status updates during upload

🐞 Troubleshooting

Q: Preview modal not opening?
A: Ensure enablePreviewModal is not set to false and check browser CSP for blob URL issues.

Q: Custom styles not applying?
A: Make sure styles are global or use ::ng-deep if ViewEncapsulation is enabled.

Q: Drag-and-drop not working?
A: Verify no parent elements are intercepting drag events.

Q: Large image not compressing enough?
A: Adjust initialQuality or maxWidthOrHeight in compressionOptions.

📄 License

MIT License © 2025 Osman.
Contributions are welcome! Open an issue or PR on GitHub. 🚀