{"id":16610156,"url":"https://github.com/lizychy0329/we-cropper","last_synced_at":"2026-05-08T00:36:25.061Z","repository":{"id":251725323,"uuid":"838256531","full_name":"lizyChy0329/we-cropper","owner":"lizyChy0329","description":"A simple WeChat-style image cropper, implemented with vue-advanced-cropper.","archived":false,"fork":false,"pushed_at":"2024-10-29T02:05:49.000Z","size":2247,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-30T18:39:29.823Z","etag":null,"topics":["cropper","tailwindcss","typescript","vue","vue3","wechat"],"latest_commit_sha":null,"homepage":"https://lizychy0329.github.io/we-cropper/","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lizyChy0329.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-05T09:15:44.000Z","updated_at":"2024-10-29T02:05:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"28679df3-7477-4980-b550-b1142dfb84bd","html_url":"https://github.com/lizyChy0329/we-cropper","commit_stats":null,"previous_names":["lizy0329-biubiubiu/we-cropper"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lizyChy0329%2Fwe-cropper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lizyChy0329%2Fwe-cropper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lizyChy0329%2Fwe-cropper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lizyChy0329%2Fwe-cropper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lizyChy0329","download_url":"https://codeload.github.com/lizyChy0329/we-cropper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238856088,"owners_count":19542142,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cropper","tailwindcss","typescript","vue","vue3","wechat"],"created_at":"2024-10-12T01:29:29.596Z","updated_at":"2025-10-29T17:30:59.384Z","avatar_url":"https://github.com/lizyChy0329.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://files.catbox.moe/cmdn41.svg\" height=\"120\" alt=\"we-cropper logo\" /\u003e\n  \u003ch1\u003ewe-cropper\u003c/h1\u003e\n  \u003cp\u003e\n    \u003cstrong\u003eA simple and powerful WeChat-style image cropper with Vue 3\u003c/strong\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@lizychy0329/we-cropper\"\u003e\n      \u003cimg alt=\"NPM Version\" src=\"https://img.shields.io/npm/v/%40lizychy0329%2Fwe-cropper?color=25234c1\u0026link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F%40lizychy0329%2Fwe-cropper\"\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n## Features\n\n- ✨ **Easy to Use**: Simple API with just one core `useCropper` hook\n- 🦾 **Strongly Typed**: Full TypeScript support with comprehensive type definitions\n- 🌍 **i18n Support**: Built-in internationalization with 9 languages and custom locale support\n- 🚀 **Fixed Cropping Box**: Consistent cropping area with configurable aspect ratio\n- 🎯 **Auto Zoom**: Automatically zooms in on the crop area for precise editing\n- ⭕ **Multiple Shapes**: Support for both rectangle and circle cropping modes\n- ❄️ **ESM / UMD Support**: Works seamlessly in both modern and legacy environments\n\n## Requirements\n\n```json\n{\n  \"peerDependencies\": {\n    \"vue\": \"^3.0.0\"\n  }\n}\n```\n\n## Installation\n\n```bash\npnpm add @lizychy0329/we-cropper\n```\n\n## Quick Start\n\n```typescript\nimport { fileToBase64, useCropper } from '@lizychy0329/we-cropper'\n\n// Initialize cropper with basic configuration\nconst { showCropper, onCrop } = useCropper({\n  el: '#cropper-container', // defaults to document.body\n  aspectRatio: 1 / 1,\n  locale: 'en' // built-in English support\n})\n\n// Handle file selection with @vueuse/useFileDialog\nconst { onChange } = useFileDialog({\n  multiple: false,\n  accept: 'image/*'\n})\n\nconst croppedImage = ref('')\nonChange(async (files) =\u003e {\n  const base64String = await fileToBase64(files[0])\n  showCropper(base64String)\n})\n\n// Handle cropped result\nonCrop((base64String) =\u003e {\n  croppedImage.value = base64String\n  // Upload to your server or further processing\n})\n```\n\n### Circle Cropping Example\n\n```typescript\nimport { fileToBase64, useCropper } from '@lizychy0329/we-cropper'\n\n// Initialize cropper with circle shape for avatar cropping\nconst { showCropper, onCrop } = useCropper({\n  shape: 'circle', // Use circle cropping mode\n  aspectRatio: 1 / 1, // Perfect square ratio for circle\n  locale: 'en'\n})\n\n// Usage remains the same\nconst { onChange } = useFileDialog({\n  multiple: false,\n  accept: 'image/*'\n})\n\nconst avatarImage = ref('')\nonChange(async (files) =\u003e {\n  const base64String = await fileToBase64(files[0])\n  showCropper(base64String, {\n    shape: 'circle', // Or Use circle cropping mode in showCropper Dynamic\n  })\n})\n\nonCrop((base64String) =\u003e {\n  avatarImage.value = base64String\n  // Perfect circular avatar ready for upload\n})\n```\n\n## Internationalization (i18n)\n\n### Built-in Languages\n\nwe-cropper supports 9 languages out of the box:\n\n| Code | Language | File |\n|------|----------|------|\n| `en` | English | en.ts |\n| `zh-CN` | Chinese (Simplified) | zh-CN.ts |\n| `zh-TW` | Chinese (Traditional) | zh-TW.ts |\n| `ja` | Japanese | ja.ts |\n| `ko` | Korean | ko.ts |\n| `fr` | French | fr.ts |\n| `de` | German | de.ts |\n| `es` | Spanish | es.ts |\n| `ru` | Russian | ru.ts |\n\n### Basic Usage\n\n```typescript\nimport { useCropper } from '@lizychy0329/we-cropper'\n\n// Use built-in language\nconst { showCropper } = useCropper({\n  locale: 'zh-CN' // Chinese interface\n})\n\nshowCropper('data:image/png;base64,...')\n```\n\n### Dynamic Language Switching\n\n```typescript\nimport { useCropper } from '@lizychy0329/we-cropper'\n\nconst { showCropper, setLocale, currentLocale } = useCropper({\n  locale: 'en'\n})\n\n// Switch language dynamically\nfunction switchToChinese(): void {\n  setLocale('zh-CN')\n  console.log(currentLocale.value) // 'zh-CN'\n}\n\n// Show cropper with current language\nshowCropper('data:image/png;base64,...')\n```\n\n### Custom Localization\n\n```typescript\nimport { useCropper } from '@lizychy0329/we-cropper'\n\nconst customLocale = {\n  en: {\n    loading: 'Processing image...',\n    reset: 'Reset Image',\n    confirm: 'Confirm Crop',\n    cancel: 'Cancel Operation',\n    rotate: 'Rotate Image',\n    error: {\n      loadImage: 'Failed to load image',\n      cropImage: 'Failed to crop image'\n    },\n    tooltip: {\n      rotate: 'Click to rotate image',\n      reset: 'Reset to original state'\n    }\n  }\n}\n\nconst { showCropper } = useCropper({\n  locale: 'en',\n  customLocale\n})\n```\n\n## API Reference\n\n### useCropper\n\n```typescript\nfunction useCropper(options?: UseCropperOptions): {\n  onCrop: EventHookOn\u003cstring\u003e // Crop completion event\n  showCropper: (src: string) =\u003e void // Display cropper\n  setLocale: (locale: LocaleCode) =\u003e void // Set language\n  currentLocale: ComputedRef\u003cLocaleCode\u003e // Current language\n}\n```\n\n### UseCropperOptions\n\n```typescript\ninterface UseCropperOptions {\n  locale?: LocaleCode // Language setting\n  customLocale?: CustomLocale // Custom language pack\n  aspectRatio?: number // Crop ratio (default: 1)\n  shape?: 'rectangle' | 'circle' // Crop shape (default: 'rectangle')\n  el?: HTMLElement | string // Mount element (default: document.body)\n  // Legacy text props (deprecated but still supported)\n  loadingText?: string\n  resetText?: string\n  confirmText?: string\n  cancelText?: string\n}\n```\n\n## Utility Functions\n\n```typescript\n// Convert base64 to Blob\nexport function base64ToBlob(base64String: string): Promise\u003cBlob\u003e\n\n// Convert File to base64\nexport function fileToBase64(file: File): Promise\u003cstring\u003e\n\n// Convert URL to base64\nexport function urlToBase64(url: string, mineType?: string): Promise\u003cstring\u003e\n```\n\n## Screenshot\n\n![we-cropper interface](https://files.catbox.moe/hcjd0s.png)\n\n## Development\n\n```bash\n# Start development server\npnpm dev\n\n# Build library\npnpm build:lib\n\n# Build documentation\npnpm build:docs\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flizychy0329%2Fwe-cropper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flizychy0329%2Fwe-cropper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flizychy0329%2Fwe-cropper/lists"}