0
# Vue Cropper
1

2
Vue Cropper is a Vue.js component that provides comprehensive image cropping functionality for Vue 2 applications. It offers an elegant and feature-rich cropping interface with real-time preview capabilities, customizable cropping areas, and support for multiple image formats (JPEG, PNG, WebP).
3

4
## Package Information
5

6
- **Package Name**: vue-cropper
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install vue-cropper`
10

11
## Core Imports
12

13
Vue 2 component import:
14

15
```javascript { .api }
16
import { VueCropper } from "vue-cropper";
17
```
18

19
Vue 2 global installation:
20

21
```javascript { .api }
22
import VueCropper from 'vue-cropper';
23
Vue.use(VueCropper);
24
```
25

26
CommonJS:
27

28
```javascript
29
const { VueCropper } = require("vue-cropper");
30
```
31

32
CDN usage:
33

34
```html
35
<script src="https://cdn.jsdelivr.net/npm/vue@2.6.14/dist/vue.js"></script>
36
<script src="https://cdn.jsdelivr.net/npm/vue-cropper@0.6.5/dist/index.js"></script>
37
```
38

39
## Basic Usage
40

41
```vue
42
<template>
43
  <div class="cropper-container" style="width: 500px; height: 400px;">
44
    <VueCropper
45
      ref="cropper"
46
      :img="imageUrl"
47
      :outputSize="0.8"
48
      :outputType="'jpeg'"
49
      :info="true"
50
      :canScale="true"
51
      :autoCrop="true"
52
      :autoCropWidth="300"
53
      :autoCropHeight="200"
54
      :fixed="true"
55
      :fixedNumber="[16, 9]"
56
      @real-time="handleRealTime"
57
      @img-load="handleImageLoad"
58
    />
59
  </div>
60
  
61
  <div class="controls">
62
    <button @click="getCroppedImage">Get Cropped Image</button>
63
    <button @click="rotateLeft">Rotate Left</button>
64
    <button @click="rotateRight">Rotate Right</button>
65
  </div>
66
</template>
67

68
<script>
69
import { VueCropper } from 'vue-cropper';
70

71
export default {
72
  components: {
73
    VueCropper
74
  },
75
  data() {
76
    return {
77
      imageUrl: '/path/to/your/image.jpg'
78
    };
79
  },
80
  methods: {
81
    handleRealTime(data) {
82
      // Real-time preview data
83
      console.log('Preview data:', data);
84
    },
85
    handleImageLoad(status) {
86
      if (status === 'success') {
87
        console.log('Image loaded successfully');
88
      } else {
89
        console.error('Image failed to load');
90
      }
91
    },
92
    getCroppedImage() {
93
      this.$refs.cropper.getCropData((data) => {
94
        // data is base64 encoded cropped image
95
        console.log('Cropped image:', data);
96
      });
97
    },
98
    rotateLeft() {
99
      this.$refs.cropper.rotateLeft();
100
    },
101
    rotateRight() {
102
      this.$refs.cropper.rotateRight();
103
    }
104
  }
105
};
106
</script>
107
```
108

109
## Architecture
110

111
Vue Cropper is built around several key components:
112

113
- **Vue Component**: Single file component (`VueCropper`) that encapsulates all cropping functionality
114
- **Canvas Rendering**: Uses HTML5 Canvas for image manipulation and cropping operations
115
- **Touch Support**: Full mobile device support with touch gestures for drag, zoom, and rotation
116
- **EXIF Handling**: Automatic image orientation correction based on EXIF data
117
- **Real-time Preview**: Live preview system with customizable preview sizes and zoom levels
118
- **Plugin System**: Vue 2 plugin architecture for global installation
119

120
## Capabilities
121

122
### Component Configuration
123

124
Core component props for controlling image display, cropping behavior, and output settings. Essential for customizing the cropper to specific use cases.
125

126
```javascript { .api }
127
interface VueCropperProps {
128
  img: string | Blob | File | null;
129
  outputSize: number;
130
  outputType: string;
131
  info: boolean;
132
  canScale: boolean;
133
  autoCrop: boolean;
134
  autoCropWidth: number | string;
135
  autoCropHeight: number | string;
136
  fixed: boolean;
137
  fixedNumber: [number, number];
138
  fixedBox: boolean;
139
  full: boolean;
140
  canMove: boolean;
141
  canMoveBox: boolean;
142
  original: boolean;
143
  centerBox: boolean;
144
  high: boolean;
145
  infoTrue: boolean;
146
  maxImgSize: number | string;
147
  enlarge: number | string;
148
  mode: string;
149
  limitMinSize: number | Array<number> | string;
150
  fillColor: string;
151
}
152
```
153

154
[Component Configuration](./component-configuration.md)
155

156
### Event Handling
157

158
Event system for responding to image loading, cropping interactions, and real-time preview updates. Critical for integrating cropper feedback into your application.
159

160
```javascript { .api }
161
interface VueCropperEvents {
162
  'img-load': (status: 'success' | 'error' | Error) => void;
163
  'img-load-error': (error: Error) => void;
164
  'img-moving': (data: MovingData) => void;
165
  'crop-moving': (data: MovingData) => void;
166
  'real-time': (data: PreviewData) => void;
167
  'change-crop-size': (data: CropSizeData) => void;
168
}
169

170
interface MovingData {
171
  moving: boolean;
172
  axis: {
173
    x1: number;
174
    x2: number;
175
    y1: number;
176
    y2: number;
177
  };
178
}
179

180
interface PreviewData {
181
  url: string;
182
  img: string;
183
  div: string;
184
  w: number;
185
  h: number;
186
}
187
```
188

189
[Event Handling](./event-handling.md)
190

191
### Programmatic Control
192

193
Methods for controlling the cropper programmatically, including crop operations, image transformations, and data extraction.
194

195
```javascript { .api }
196
interface VueCropperMethods {
197
  startCrop(): void;
198
  stopCrop(): void;
199
  clearCrop(): void;
200
  goAutoCrop(): void;
201
  changeScale(delta: number): void;
202
  rotateLeft(): void;
203
  rotateRight(): void;
204
  rotateClear(): void;
205
  changeCrop(w: number, h: number): void;
206
  refresh(): void;
207
  getCropData(callback: (base64: string) => void): void;
208
  getCropBlob(callback: (blob: Blob) => void): void;
209
  getImgAxis(): AxisData;
210
  getCropAxis(): AxisData;
211
  readonly cropW: number;
212
  readonly cropH: number;
213
}
214

215
interface AxisData {
216
  x1: number;
217
  x2: number;
218
  y1: number;
219
  y2: number;
220
}
221
```
222

223
[Programmatic Control](./programmatic-control.md)
224

225
## Global Plugin Interface
226

227
```javascript { .api }
228
interface VueCropperGlobal {
229
  version: string;
230
  install: (Vue: any) => void;
231
  VueCropper: typeof VueCropper;
232
}
233
```
234

235
The default export provides the global plugin interface for Vue 2 installation via `Vue.use()`.