ImageUploader

docs generated using Junie AI

A comprehensive web component for uploading, editing, and managing images with gallery view.

Overview

ImageUploader is a feature-rich web component that provides a complete solution for image management in web applications. It allows users to upload images, edit them using the integrated ImageEditor, view them in a gallery, and manage them with various operations like sorting and deleting.

Key Features

• Image Upload: Support for drag-and-drop and file selection
• Image Editing: Integrated with ImageEditor for cropping, resizing, rotating, and applying filters
• Gallery View: Display uploaded images in a grid layout
• Image Slider: View images in a fullscreen slider
• Sorting: Reorder images via drag-and-drop
• Validation: Validate image dimensions, file size, and format
• Responsive Design: Works on desktop and mobile devices
• Internationalization: Support for multiple languages via the Translator package

Installation

npm install @mlbrgn/image-uploader

Usage

Basic Setup

Import the component in your JavaScript file:

import '@mlbrgn/image-uploader';

Add the component to your HTML:

<image-uploader></image-uploader>

Configuration

You can configure the uploader using attributes:

<image-uploader
  required
  min-width="800"
  min-height="600"
  max-width="1920"
  max-height="1080"
  aspect-ratios="1:1,16:9,4:3"
  force-aspect-ratio="16:9">
</image-uploader>

Setting Initial Images

You can set initial images programmatically or via the images attribute:

const uploader = document.querySelector('image-uploader');
const images = [
  { src: 'path/to/image1.jpg', alt: 'Image 1' },
  { src: 'path/to/image2.jpg', alt: 'Image 2' }
];

uploader.setImages(images);

<image-uploader images='[{"src":"path/to/image1.jpg","alt":"Image 1"},{"src":"path/to/image2.jpg","alt":"Image 2"}]'></image-uploader>

Getting Selected Images

const uploader = document.querySelector('image-uploader');
const images = uploader.getImages();
console.log(images);

Form Integration

The component can be used within forms and supports the required attribute:

<form>
  <image-uploader name="product-images" required></image-uploader>
  <button type="submit">Submit</button>
</form>

Configuration Options

| Attribute | Type | Default | Description | |-----------|------|---------|-------------| | required | Boolean | false | Whether image upload is required | | disabled | Boolean | false | Disables the uploader | | delete-disabled | Boolean | false | Disables image deletion | | sort-disabled | Boolean | false | Disables image reordering | | min-width | Number | 0 | Minimum image width in pixels | | min-height | Number | 0 | Minimum image height in pixels | | max-width | Number | 0 | Maximum image width in pixels | | max-height | Number | 0 | Maximum image height in pixels | | aspect-ratios | String | "" | Comma-separated list of aspect ratios (e.g., "1:1,16:9,4:3") | | force-aspect-ratio | String | "" | Forces a specific aspect ratio for all images | | free-select-disabled | Boolean | false | Disables free selection in editor | | free-rotate-disabled | Boolean | false | Disables free rotation in editor | | filters-disabled | Boolean | false | Disables filters in editor | | fade-duration | Number | 350 | Duration of fade transition in slider |

Events

The uploader emits events that you can listen for:

const uploader = document.querySelector('image-uploader');
uploader.addEventListener('images-changed', (event) => {
  console.log('Images changed:', event.detail.images);
});

| Event | Description | |-------|-------------| | images-changed | Fired when the collection of images changes | | image-upload-start | Fired when image upload starts | | image-upload-complete | Fired when image upload completes | | image-edit-start | Fired when image editing starts | | image-edit-complete | Fired when image editing completes | | image-delete | Fired when an image is deleted |

Development

This package is developed inside the mlbrgn-node-workspace monorepo. Do not run npm run dev or npm install inside this repository.

Clone the monorepo instead: https://github.com/evertjanmlbrgn/mlbrgn-node-workspace