{"id":45277746,"url":"https://github.com/marshallino16/imagecropper","last_synced_at":"2026-02-21T02:00:50.298Z","repository":{"id":49478599,"uuid":"322639733","full_name":"marshallino16/ImageCropper","owner":"marshallino16","description":"Simple ratio based image cropper for SwiftUI","archived":false,"fork":false,"pushed_at":"2021-06-16T21:36:51.000Z","size":89,"stargazers_count":38,"open_issues_count":2,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2023-06-05T14:40:17.497Z","etag":null,"topics":["cropper","image-cropper","image-cropping","images","ios","swift","swiftui"],"latest_commit_sha":null,"homepage":"","language":"Swift","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/marshallino16.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}},"created_at":"2020-12-18T15:56:47.000Z","updated_at":"2023-04-22T13:28:46.000Z","dependencies_parsed_at":"2022-09-17T22:12:22.726Z","dependency_job_id":null,"html_url":"https://github.com/marshallino16/ImageCropper","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"purl":"pkg:github/marshallino16/ImageCropper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marshallino16%2FImageCropper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marshallino16%2FImageCropper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marshallino16%2FImageCropper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marshallino16%2FImageCropper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marshallino16","download_url":"https://codeload.github.com/marshallino16/ImageCropper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marshallino16%2FImageCropper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29671513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T00:11:43.526Z","status":"online","status_checked_at":"2026-02-21T02:00:07.432Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","image-cropper","image-cropping","images","ios","swift","swiftui"],"created_at":"2026-02-21T02:00:49.429Z","updated_at":"2026-02-21T02:00:50.291Z","avatar_url":"https://github.com/marshallino16.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eSwiftUI-ImageCropper\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    A modern, ratio-based image cropper for SwiftUI.\u003cbr\u003e\n    The crop frame stays fixed while the user pans and zooms the image underneath —\u003cbr\u003ejust like iOS Photos or Instagram.\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/tag/marshallino16/ImageCropper?style=flat-square\u0026label=version\u0026color=blue\" alt=\"Version\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Swift_5.3+-F05138?style=flat-square\u0026logo=swift\u0026logoColor=white\" alt=\"Swift 5.3+\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/SPM-compatible-4BC51D?style=flat-square\u0026logo=swift\" alt=\"SPM\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/iOS_13+-000000?style=flat-square\u0026logo=apple\" alt=\"iOS 13+\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/macOS_10.15+-000000?style=flat-square\u0026logo=apple\" alt=\"macOS 10.15+\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/marshallino16/ImageCropper?style=flat-square\" alt=\"License\"\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"700\" alt=\"SwiftUI-ImageCropper Demo\" src=\"https://user-images.githubusercontent.com/1506323/102635181-4293b700-4153-11eb-81aa-1175d58b4464.png\"\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n---\n\n## Highlights\n\n- **Pan \u0026 pinch-to-zoom** with anchor at finger midpoint\n- **Rubber-band** elastic drag beyond crop bounds with animated snap-back\n- **Multiple grid styles** — rule of thirds, golden ratio, diagonal, crosshair\n- **Crop shapes** — rectangle, circle, rounded rectangle\n- **Double-tap/click** to toggle zoom\n- **Programmatic reset \u0026 image export** via binding triggers\n- **Haptic feedback** on iOS when dragging past bounds\n- **Preset aspect ratios** — `1:1`, `3:2`, `4:3`, `16:9` (or define your own)\n- **Normalized `CGRect` output** (0–1 range) for easy image processing\n- **Fully configurable** via SwiftUI modifiers — all options are opt-in\n- **Cross-platform** — iOS 13+ and macOS 10.15+\n\n---\n\n## Installation\n\n### Swift Package Manager\n\nAdd the package to your Xcode project:\n\n**File** → **Add Package Dependencies** → paste the URL:\n\n```\nhttps://github.com/marshallino16/ImageCropper\n```\n\nOr add it to your `Package.swift`:\n\n```swift\ndependencies: [\n  .package(url: \"https://github.com/marshallino16/ImageCropper\", from: \"1.0.0\")\n]\n```\n\n---\n\n## Quick Start\n\n### iOS\n\n```swift\nimport ImageCropper\n\nImageCropperView(image: UIImage(named: \"photo\")!, ratio: .r_1_1)\n  .onCropChanged { cropRect in\n    print(cropRect) // normalized CGRect (0–1)\n  }\n```\n\n### macOS\n\n```swift\nimport ImageCropper\n\nImageCropperView(image: NSImage(named: \"photo\")!, ratio: .r_1_1)\n  .onCropChanged { cropRect in\n    print(cropRect)\n  }\n```\n\n### SwiftUI Image (cross-platform)\n\n```swift\nImageCropperView(image: Image(\"photo\"),\n                 imageSize: CGSize(width: 1920, height: 1080),\n                 ratio: .r_16_9)\n  .onCropChanged { cropRect in\n    print(cropRect)\n  }\n```\n\n---\n\n## Full Example\n\n```swift\n@State private var shouldReset = false\n@State private var shouldCrop = false\n\nImageCropperView(image: UIImage(named: \"photo\")!, ratio: .r_4_3)\n  .onCropChanged { cropRect in print(cropRect) }\n\n  // Visual\n  .backgroundColor(.black)\n  .overlayStyle(color: .black, opacity: 0.55)\n  .cornerStyle(color: .white, size: 20, weight: 2)\n  .cropShape(.circle)\n  .gridStyle(.goldenRatio)\n  .gridColor(.white, lineWidth: 0.5, opacity: 0.6)\n  .alwaysShowGrid(true)\n\n  // Behavior\n  .zoomRange(1.0...8.0)\n  .snapBackAnimation(.spring(response: 0.4, dampingFraction: 0.8))\n  .rubberBandEnabled(true)\n  .rubberBandFactor(0.35)\n\n  // Interactions\n  .doubleTapToZoom(enabled: true, targetScale: 2.0)\n  .hapticFeedback(true) // iOS only\n\n  // Triggers\n  .resetTrigger($shouldReset)\n  .cropTrigger($shouldCrop)\n  .onCropImage { croppedImage in\n    // croppedImage is UIImage (iOS) or NSImage (macOS)\n  }\n```\n\n---\n\n## Init Parameters\n\n| Parameter | Type | Default | Required |\n|-----------|------|---------|:--------:|\n| `image` | `UIImage` / `NSImage` / `Image` | — | Yes |\n| `imageSize` | `CGSize` | — | Only with `Image` init |\n| `cropRect` | `CGRect?` | `nil` | No |\n| `ratio` | `CropperRatio` | — | Yes |\n\n---\n\n## Modifiers\n\n### Core\n\n| Modifier | Description |\n|----------|-------------|\n| `.onCropChanged { CGRect in }` | Called whenever the visible crop region changes |\n| `.alwaysShowGrid(true)` | Show the grid permanently (default: only during interaction) |\n\n### Visual\n\n| Modifier | Default | Description |\n|----------|---------|-------------|\n| `.backgroundColor(_:)` | `.black` | Background color behind the image |\n| `.overlayStyle(color:opacity:)` | black, 0.55 | Dimmed area outside the crop frame |\n| `.cornerStyle(color:size:weight:)` | white, 20, 2 | Corner guide appearance |\n| `.cropShape(_:)` | `.rectangle` | `.rectangle` · `.circle` · `.roundedRect(cornerRadius:)` |\n| `.gridStyle(_:)` | `.ruleOfThirds` | `.ruleOfThirds` · `.goldenRatio` · `.diagonal` · `.crosshair` · `.none` |\n| `.gridColor(_:lineWidth:opacity:)` | white, 0.5, 0.6 | Grid line appearance |\n\n### Behavior\n\n| Modifier | Default | Description |\n|----------|---------|-------------|\n| `.zoomRange(_:)` | `1.0...5.0` | Allowed zoom scale range |\n| `.snapBackAnimation(_:)` | `.easeInOut(0.3)` | Animation when the image settles after a gesture |\n| `.rubberBandEnabled(_:)` | `true` | Enable elastic drag beyond crop bounds |\n| `.rubberBandFactor(_:)` | `0.35` | Dampening factor (0 = none, 1 = full stretch) |\n\n### Interactions\n\n| Modifier | Default | Description |\n|----------|---------|-------------|\n| `.doubleTapToZoom(enabled:targetScale:)` | off, 2.0 | Toggle zoom on double-tap/click |\n| `.hapticFeedback(_:)` | `false` | Haptic when dragging past bounds (iOS only) |\n\n### Triggers \u0026 Export\n\n| Modifier | Description |\n|----------|-------------|\n| `.resetTrigger($binding)` | Set to `true` to reset scale \u0026 offset (auto-resets to `false`) |\n| `.cropTrigger($binding)` | Set to `true` to trigger crop export (auto-resets to `false`) |\n| `.onCropImage { PlatformImage in }` | Receive the cropped `UIImage`/`NSImage` when crop fires |\n\n---\n\n## Preset Ratios\n\n| Preset | Value |\n|--------|:-----:|\n| `CropperRatio.r_1_1` | 1 : 1 |\n| `CropperRatio.r_3_2` | 3 : 2 |\n| `CropperRatio.r_4_3` | 4 : 3 |\n| `CropperRatio.r_16_9` | 16 : 9 |\n\nCustom ratios:\n```swift\nCropperRatio(width: 21, height: 9)\n```\n\n---\n\n## Types\n\n```swift\n// Cross-platform image type alias\n#if iOS\npublic typealias PlatformImage = UIImage\n#else\npublic typealias PlatformImage = NSImage\n#endif\n\n// Crop shape\npublic enum CropShape: Equatable, Sendable {\n  case rectangle\n  case circle\n  case roundedRect(cornerRadius: CGFloat)\n}\n\n// Grid style\npublic enum GridStyle: Sendable {\n  case ruleOfThirds\n  case goldenRatio\n  case diagonal\n  case crosshair\n  case none\n}\n```\n\n---\n\n## Demo Apps\n\nThe repository includes two demo apps showcasing every modifier and option:\n\n| App | Location | Description |\n|-----|----------|-------------|\n| **Demo-macOS** | `Demo-macOS/` | macOS app with HSplitView — cropper + sidebar controls |\n| **Demo-iOS** | `Demo-iOS/` | iOS app with top cropper + scrollable controls below |\n\nOpen the workspace to build both:\n\n```bash\nopen SwiftUI-ImageCropper.xcworkspace\n```\n\n---\n\n## Architecture\n\n```\nSources/ImageCropper/\n├── ImageCropperView.swift    # Public API — SwiftUI View with all modifiers\n├── CropperView.swift         # Internal UI — ZStack, gesture handling, crop math\n├── CropperConfiguration.swift# All configurable values in one struct\n├── CropperRatio.swift        # Aspect ratio value type with presets\n├── CropShape.swift           # Rectangle / circle / rounded rect enum\n├── GridStyle.swift            # Grid overlay pattern enum\n├── GridOverlay.swift          # Grid drawing view (5 styles)\n├── CornerGuides.swift         # L-shaped corner guide view\n├── CropHoleShape.swift        # Even-odd cutout shape\n├── ChangeObserver.swift       # onChange polyfill for iOS 13 / macOS 10.15\n├── NativeGestureOverlay.swift # UIKit \u0026 AppKit gesture bridge\n└── PlatformTypes.swift        # PlatformImage typealias + crop helper\n```\n\n**Data flow:**\n`ImageCropperView` → `GeometryReader` → `CropperView` → `NativeGestureOverlay` captures gestures → crop rect computed → `.onCropChanged` fires with normalized `CGRect`\n\n---\n\n## Requirements\n\n| Requirement | Minimum |\n|-------------|---------|\n| Xcode | 12+ |\n| Swift | 5.3+ |\n| iOS | 13.0+ |\n| macOS | 10.15+ |\n\n---\n\n## License\n\nImageCropper is available under the **MIT license**. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarshallino16%2Fimagecropper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarshallino16%2Fimagecropper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarshallino16%2Fimagecropper/lists"}