pica-resize-image/README.md

A resize image plugin for Pica

# pica-resize-image

[![npm version](https://img.shields.io/npm/v/pica-resize-image.svg)](https://www.npmjs.com/package/pica-resize-image)
[![npm downloads](https://img.shields.io/npm/dm/pica-resize-image.svg)](https://www.npmjs.com/package/pica-resize-image)
[![license](https://img.shields.io/npm/l/pica-resize-image.svg)](https://github.com/theanh-it/pica-resize-image/blob/main/LICENSE)

**Version: 0.0.6**

**[English](#) | [Tiếng Việt](./README.vi.md)**

A high-quality image resize library for browser using Pica, with **HEIC/HEIF support**.

## Features

- ✅ High-quality image resizing using Pica
- ✅ Support multiple output formats (WebP, PNG, JPEG)
- ✅ Support multiple output types (File, Blob, Base64)
- ✅ **HEIC/HEIF support** - automatic conversion
- ✅ Cover mode - smart crop to fit dimensions
- ✅ Batch processing - resize multiple images
- ✅ TypeScript support
- ✅ Zero config - works out of the box

## Installation

```bash
npm install pica-resize-image pica heic2any
```

or

```bash
yarn add pica-resize-image pica heic2any
```

or

```bash
bun add pica-resize-image pica heic2any
```

## Usage

### Basic Usage

```typescript
import { resizeImage, MIME_TYPE } from "pica-resize-image";

const file = /* File from input[type="file"] */;

const resized = await resizeImage(file, {
  width: 800,
  height: 600,
  mimeType: MIME_TYPE.webp,
  quality: 0.9,
});

console.log(resized); // File object
```

### Resize by Width (maintain aspect ratio)

```typescript
const resized = await resizeImage(file, {
  width: 800,
});
```

### Resize by Height (maintain aspect ratio)

```typescript
const resized = await resizeImage(file, {
  height: 600,
});
```

### Cover Mode (crop to fit)

```typescript
const resized = await resizeImage(file, {
  width: 800,
  height: 600,
  cover: true, // Crop image to fill exact dimensions
});
```

### Output as Base64

```typescript
import { OUTPUT_TYPE } from "pica-resize-image";

const base64 = await resizeImage(file, {
  width: 800,
  output: OUTPUT_TYPE.base64,
});

console.log(base64); // "data:image/webp;base64,..."
```

### Output as Blob

```typescript
const blob = await resizeImage(file, {
  width: 800,
  output: OUTPUT_TYPE.blob,
});

console.log(blob); // Blob { size: 12345, type: "image/webp" }
```

### Batch Processing

```typescript
import { resizeImages } from "pica-resize-image";

const files = /* File[] from input[type="file"] multiple */;

const resized = await resizeImages(files, {
  width: 800,
  mimeType: MIME_TYPE.jpeg,
  quality: 0.85,
});

console.log(resized); // File[]
```

## HEIC Support

HEIC/HEIF images (iPhone photos) are automatically detected and converted to JPEG before resizing.

```typescript
const heicFile = /* HEIC file from iPhone */;

// Works automatically - no special config needed!
const resized = await resizeImage(heicFile, {
  width: 800,
  mimeType: MIME_TYPE.webp,
});

// Result: WebP file (HEIC → JPEG → WebP)
```

**Note:** HEIC conversion adds ~1-2 seconds to processing time.

## API

### `resizeImage(image, options?)`

Resize a single image.

**Parameters:**

- `image: File` - Image file to resize
- `options?: ResizeImageOptions` - Resize options

**Returns:** `Promise<File | Blob | string>` - Resized image

### `resizeImages(images, options?)`

Resize multiple images.

**Parameters:**

- `images: File[]` - Array of image files
- `options?: ResizeImageOptions` - Resize options

**Returns:** `Promise<(File | Blob | string)[]>` - Array of resized images

### `ResizeImageOptions`

```typescript
type ResizeImageOptions = {
  width?: number; // Target width in pixels
  height?: number; // Target height in pixels
  cover?: boolean; // Crop to fill exact dimensions (like background-size: cover)
  mimeType?: MimeType; // Output format (default: webp)
  quality?: number; // Quality 0-1 (default: 1)
  output?: OutputType; // Output type (default: "file")
};
```

### Constants

```typescript
// Output types
OUTPUT_TYPE.file; // File object
OUTPUT_TYPE.blob; // Blob object
OUTPUT_TYPE.base64; // Base64 string

// MIME types
MIME_TYPE.webp; // image/webp (default, best compression)
MIME_TYPE.png; // image/png (lossless)
MIME_TYPE.jpeg; // image/jpeg (smaller size)
```

## Examples

### Example 1: Image Upload with Preview

```html
<input type="file" id="upload" accept="image/*,.heic,.heif" />
<img id="preview" />

<script type="module">
  import { resizeImage, OUTPUT_TYPE } from "pica-resize-image";

  document.getElementById("upload").addEventListener("change", async (e) => {
    const file = e.target.files[0];

    const base64 = await resizeImage(file, {
      width: 400,
      output: OUTPUT_TYPE.base64,
    });

    document.getElementById("preview").src = base64;
  });
</script>
```

### Example 2: Batch Upload

```javascript
import { resizeImages, MIME_TYPE } from "pica-resize-image";

async function handleFiles(files) {
  console.log(`Processing ${files.length} images...`);

  const resized = await resizeImages(files, {
    width: 1200,
    mimeType: MIME_TYPE.webp,
    quality: 0.85,
  });

  console.log(`Done! Resized ${resized.length} images.`);
  return resized;
}
```

### Example 3: Form Upload

```javascript
import { resizeImage, MIME_TYPE } from "pica-resize-image";

async function uploadToServer(file) {
  // Resize before upload to reduce bandwidth
  const resized = await resizeImage(file, {
    width: 1920,
    mimeType: MIME_TYPE.jpeg,
    quality: 0.85,
  });

  const formData = new FormData();
  formData.append("image", resized);

  await fetch("/api/upload", {
    method: "POST",
    body: formData,
  });
}
```

## Browser Compatibility

- Chrome 61+
- Firefox 60+
- Safari 11+
- Edge 79+

**HEIC support** requires WebAssembly (all modern browsers).

## Performance

| Operation      | File Size | Time       |
| -------------- | --------- | ---------- |
| Resize JPG/PNG | < 1MB     | 100-300ms  |
| Resize JPG/PNG | 1-5MB     | 500-1500ms |
| Resize HEIC    | < 1MB     | 1-2s       |
| Resize HEIC    | 1-5MB     | 2-4s       |

## TypeScript

Full TypeScript support included.

```typescript
import {
  resizeImage,
  resizeImages,
  type ResizeImageOptions,
  type OutputType,
  type MimeType,
} from "pica-resize-image";
```

## Testing

```bash
# Run tests
npm test

# or
bun test
```

## License

MIT

## Links

- [GitHub](https://github.com/theanh-it/pica-resize-image)
- [NPM](https://www.npmjs.com/package/pica-resize-image)
- [Pica](https://github.com/nodeca/pica)
- [heic2any](https://github.com/alexcorvi/heic2any)

## Credits

- [Pica](https://github.com/nodeca/pica) - High quality image resize in browser
- [heic2any](https://github.com/alexcorvi/heic2any) - HEIC to JPEG conversion