---
metaTitle: Cropper component | AwesCode UI
meta:
  - name: description
    content: The <AwCropper /> component is used to render Cropper - UI Vue component for AwesCode UI.
title: Cropper
---

# AwCropper

**Category:** Organism | **Import:** Dynamic

The `AwCropper` component is an image cropping tool built on Croppie.js. It allows users to select and crop a portion of an image with rotation support and customizable output dimensions.

## Overview

`AwCropper` provides an image cropping solution with:
- Interactive crop area selection
- Image rotation (90° increments)
- Customizable viewport and output dimensions
- Circle or square crop shapes
- Format and quality control
- Mobile-friendly touch support

## Usage

### Basic Example

```markup
<AwCropper 
    src="/path/to/image.jpg"
    :width="200"
    :height="200"
    @save="handleCrop"
/>
```

### Square Crop

```markup
<AwCropper 
    src="/path/to/image.jpg"
    :width="300"
    :height="300"
    square
    @save="handleCrop"
/>
```

### Custom Output Size

```markup
<AwCropper 
    src="/path/to/image.jpg"
    :width="200"
    :height="200"
    :save-width="800"
    :save-height="800"
    format="jpeg"
    :quality="0.9"
    @save="handleCrop"
/>
```

### Custom Buttons

```markup
<AwCropper 
    src="/path/to/image.jpg"
    :width="200"
    :height="200"
    @save="handleCrop"
    @cancel="handleCancel"
>
    <template #buttons="{ rotate, save }">
        <AwButton @click="rotate">Rotate</AwButton>
        <AwButton @click="save" color="accent">Save</AwButton>
        <AwButton @click="$emit('cancel')">Cancel</AwButton>
    </template>
</AwCropper>
```

## API

### Props

| Name | Description | Type | Required | Default |
|------|-------------|------|----------|---------|
| src | Source image URL | `String` | `true` | - |
| width | Viewport width in pixels | `String` / `Number` | `false` | `200` |
| height | Viewport height in pixels | `String` / `Number` | `false` | `200` |
| saveWidth | Output image width in pixels | `Number` | `false` | `800` |
| saveHeight | Output image height in pixels | `Number` | `false` | `800` |
| padding | Padding around viewport | `String` / `Number` | `false` | `100` |
| format | Output format: `'png'` or `'jpeg'` | `String` | `false` | `'png'` |
| quality | Output quality (0-1, JPEG only) | `String` / `Number` | `false` | `1` |
| square | Use square crop shape (instead of circle) | `Boolean` | `false` | `false` |

### Slots

| Name | Description | Props | Default Slot Content |
|------|-------------|-------|---------------------|
| buttons | Custom buttons area | `{ rotate, save }` | Default rotate and save buttons |
| upload | Upload area (not used in current implementation) | - | - |

### Events

| Name | Payload | Description |
|------|---------|-------------|
| save | `Blob` | Emitted when save is clicked, returns cropped image as Blob |
| cancel | - | Emitted when cancel is clicked (if handled) |

### Methods

| Name | Parameters | Description |
|------|------------|-------------|
| rotate | - | Rotate image 90° counter-clockwise |
| save | - | Trigger save (emits `save` event with Blob) |
| refresh | - | Refresh cropper with current image |

### Config Options

The component uses default configuration from `@AwConfig`. You can override these defaults in your project's `awes.config.js`:

```javascript
export default {
  AwCropper: {
    baseClass: 'aw-cropper'
  }
}
```

## Related Components

- `AwButton` - Button component for actions
- `AwImageUpload` - Image upload component

## Notes

- **Import Method:** Dynamic - Component is loaded on-demand as an organism
- Uses Croppie.js library for image cropping functionality
- Viewport defines the visible crop area
- Output dimensions (`saveWidth`/`saveHeight`) define the final image size
- Format `'png'` supports transparency, `'jpeg'` does not
- Quality only affects JPEG output (0-1 range)
- Square mode creates square crop area, otherwise circle
- Rotation is in 90° increments (counter-clockwise)
- Pinch zoom is prevented on mobile devices
- Component initializes Croppie on mount
- Image orientation is automatically handled
- Save returns a Blob that can be used with FileReader or FormData