npm package: @mlbrgn/image-uploader
Description: A comprehensive web component for uploading, editing, and managing images with gallery view
Author: Evertjan Garretsen
Latest version: 1.0.67

# ImageUploader

docs generated using Junie AI

[![Run tests and bump version](https://github.com/evertjanMlbrgn/ImageUploader/actions/workflows/test-and-publish-version-bumped-package.yml/badge.svg)](https://github.com/evertjanMlbrgn/ImageUploader/actions/workflows/test-and-publish-version-bumped-package.yml)
[![Super-linter (lint files)](https://github.com/evertjanMlbrgn/ImageUploader/actions/workflows/super-linter.yml/badge.svg)](https://github.com/evertjanMlbrgn/ImageUploader/actions/workflows/super-linter.yml)

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

```bash
npm install @mlbrgn/image-uploader
```

## Usage

### Basic Setup

Import the component in your JavaScript file:

```javascript
import '@mlbrgn/image-uploader';
```

Add the component to your HTML:

```html
<image-uploader></image-uploader>
```

### Configuration

You can configure the uploader using attributes:

```html
<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:

```javascript
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);
```

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

### Getting Selected Images

```javascript
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:

```html
<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:

```javascript
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