{"id":1472,"url":"https://github.com/JanGorman/Agrume","last_synced_at":"2025-08-06T13:32:27.917Z","repository":{"id":32549159,"uuid":"36131454","full_name":"JanGorman/Agrume","owner":"JanGorman","description":"🍋 A lemony fresh iOS image viewer written in Swift.","archived":false,"fork":false,"pushed_at":"2024-10-29T07:56:31.000Z","size":2696,"stargazers_count":815,"open_issues_count":0,"forks_count":121,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-12-05T13:03:35.843Z","etag":null,"topics":["carthage","cocoapods","image","image-viewer","ios","swift"],"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/JanGorman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["JanGorman"]}},"created_at":"2015-05-23T16:20:29.000Z","updated_at":"2024-12-02T22:22:23.000Z","dependencies_parsed_at":"2024-10-29T08:27:53.708Z","dependency_job_id":"55c2a7d9-ef2c-4405-8b0f-85e874d586dc","html_url":"https://github.com/JanGorman/Agrume","commit_stats":{"total_commits":511,"total_committers":38,"mean_commits":"13.447368421052632","dds":0.6203522504892368,"last_synced_commit":"8bbf24857b5ceaa092e3569f8319b3236d02f53e"},"previous_names":[],"tags_count":95,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JanGorman%2FAgrume","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JanGorman%2FAgrume/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JanGorman%2FAgrume/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JanGorman%2FAgrume/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JanGorman","download_url":"https://codeload.github.com/JanGorman/Agrume/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228905488,"owners_count":17989775,"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":["carthage","cocoapods","image","image-viewer","ios","swift"],"created_at":"2024-01-05T20:15:47.242Z","updated_at":"2024-12-09T14:30:54.736Z","avatar_url":"https://github.com/JanGorman.png","language":"Swift","funding_links":["https://github.com/sponsors/JanGorman"],"categories":["Media","Libs","UI","Images [🔝](#readme)","Swift"],"sub_categories":["Image","Images","Other free courses"],"readme":"# Agrume\n\n[![Build Status](https://travis-ci.org/JanGorman/Agrume.svg?branch=master)](https://travis-ci.org/JanGorman/Agrume) [![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n[![Version](https://img.shields.io/cocoapods/v/Agrume.svg?style=flat)](http://cocoapods.org/pods/Agrume)\n[![License](https://img.shields.io/cocoapods/l/Agrume.svg?style=flat)](http://cocoapods.org/pods/Agrume)\n[![Platform](https://img.shields.io/cocoapods/p/Agrume.svg?style=flat)](http://cocoapods.org/pods/Agrume)\n[![SPM](https://img.shields.io/badge/spm-compatible-brightgreen.svg?style=flat)](https://swift.org/package-manager)\n\nAn iOS image viewer written in Swift with support for multiple images.\n\n![Agrume](https://www.dropbox.com/s/bdt6sphcyloa38u/Agrume.gif?raw=1)\n\n## Requirements\n\n- Swift 5.0\n- iOS 9.0+\n- Xcode 10.2+\n\n## Installation\n\nUse [Swift Package Manager](https://swift.org/package-manager).\n\nOr [CocoaPods](http://cocoapods.org). Add the dependency to your `Podfile` and then run `pod install`:\n\n```ruby\npod \"Agrume\"\n```\n\nOr [Carthage](https://github.com/Carthage/Carthage). Add the dependency to your `Cartfile` and then run `carthage update`:\n\n```ogdl\ngithub \"JanGorman/Agrume\"\n```\n\n## Usage\n\nThere are multiple ways you can use the image viewer (and the included sample project shows them all).\n\nFor just a single image it's as easy as\n\n### Basic\n\n```swift\nimport Agrume\n\nprivate lazy var agrume = Agrume(image: UIImage(named: \"…\")!)\n\n@IBAction func openImage(_ sender: Any) {\n  agrume.show(from: self)\n}\n```\n\nYou can also pass in a `URL` and Agrume will take care of the download for you.\n\n### SwiftUI\n\nCurrently the SwiftUI implementation doesn't surface configurations, so can only be used as a basic image viewer - PRs welcome to extend its functionality.\n\n```swift\nimport Agrume\n\nstruct ExampleView: View {\n    \n  let images: [UIImage]\n\n  @State var showAgrume = false\n\n  var body: some View {\n    VStack {\n      // Hide the presenting button (or other view) whenever Agrume is shown\n      if !showAgrume {\n        Button(\"Launch Agrume from SwiftUI\") {\n          withAnimation {\n            showAgrume = true\n          }\n        }\n      }\n\n      if showAgrume {\n        // You can pass a single or multiple images\n        AgrumeView(images: images, isPresenting: $showAgrume)\n      }\n    }\n  }\n}\n```\n\n### Background Configuration\n\nAgrume has different background configurations. You can have it blur the view it's covering or supply a background color:\n\n```swift\nlet agrume = Agrume(image: UIImage(named: \"…\")!, background: .blurred(.regular))\n// or\nlet agrume = Agrume(image: UIImage(named: \"…\")!, background: .colored(.green))\n```\n\n### Multiple Images\n\nIf you're displaying a `UICollectionView` and want to add support for zooming, you can also call Agrume with an array of either images or URLs.\n\n```swift\n// In case of an array of [UIImage]:\nlet agrume = Agrume(images: images, startIndex: indexPath.item, background: .blurred(.light))\n// Or an array of [URL]:\n// let agrume = Agrume(urls: urls, startIndex: indexPath.item, background: .blurred(.light))\n\nagrume.didScroll = { [unowned self] index in\n  self.collectionView.scrollToItem(at: IndexPath(item: index, section: 0), at: [], animated: false)\n}\nagrume.show(from: self)\n```\n\nThis shows a way of keeping the zoomed library and the one in the background synced.\n\n### Animated gifs\n\nAgrume bundles [SwiftyGif](https://github.com/kirualex/SwiftyGif) to display animated gifs. You use SwiftyGif's custom `UIImage` initializer:\n\n```swift\nlet image = UIImage(gifName: \"animated.gif\")\nlet agrume = Agrume(image: image)\nagrume.display(from: self)\n\n// Or gif using data:\n\nlet image = UIImage(gifData: data)\nlet agrume = Agrume(image: image)\n\n// Or multiple images:\n\nlet images = [UIImage(gifName: \"animated.gif\"), UIImage(named: \"foo.png\")] // You can pass both animated and regular images at the same time\nlet agrume = Agrume(images: images)\n```\n\nRemote animated gifs (i.e. using the url or urls initializer) are supported. Agrume does the image type detection and displays them properly. If using Agrume from a custom `UIImageView` you may need to rebuild the `UIImage` using the original data to preserve animation vs. using the `UIImage` instance from the image view.\n\n### Close Button\n\nPer default you dismiss the zoomed view by dragging/flicking the image off screen. You can opt out of this behaviour and instead display a close button. To match the look and feel of your app you can pass in a custom `UIBarButtonItem`:\n\n```swift\n// Default button that displays NSLocalizedString(\"Close\", …)\nlet agrume = Agrume(image: UIImage(named: \"…\")!, .dismissal: .withButton(nil))\n// Customise the button any way you like. For example display a system \"x\" button\nlet button = UIBarButtonItem(barButtonSystemItem: .stop, target: nil, action: nil)\nbutton.tintColor = .red\nlet agrume = Agrume(image: UIImage(named: \"…\")!, .dismissal: .withButton(button))\n```\n\nThe included sample app shows both cases for reference.\n\n### Custom Download Handler\n\nIf you want to take control of downloading images (e.g. for caching), you can also set a download closure that calls back to Agrume to set the image. For example, let's use [MapleBacon](https://github.com/JanGorman/MapleBacon).\n\n```swift\nimport Agrume\nimport MapleBacon\n\nprivate lazy var agrume = Agrume(url: URL(string: \"https://dl.dropboxusercontent.com/u/512759/MapleBacon.png\")!)\n\n@IBAction func openURL(_ sender: Any) {\n  agrume.download = { url, completion in\n    Downloader.default.download(url) { image in\n      completion(image)\n    }\n  }\n  agrume.show(from: self)\n}\n```\n\n### Global Custom Download Handler\n\nInstead of having to define a handler on a per instance basis you can instead set a handler on the `AgrumeServiceLocator`. Agrume will use this handler for all downloads unless overriden on an instance as described above:\n\n```swift\nimport Agrume\n\nAgrumeServiceLocator.shared.setDownloadHandler { url, completion in\n  // Download data, cache it and call the completion with the resulting UIImage\n}\n\n// Some other place\nagrume.show(from: self)\n```\n\n### Custom Data Source\n\nFor more dynamic library needs you can implement the `AgrumeDataSource` protocol that supplies images to Agrume. Agrume will query the data source for the number of images and if that number changes, reload it's scrolling image view.\n\n```swift\nimport Agrume\n\nlet dataSource: AgrumeDataSource = MyDataSourceImplementation()\nlet agrume = Agrume(dataSource: dataSource)\n\nagrume.show(from: self)\n```\n\n### Status Bar Appearance\n\nYou can customize the status bar appearance when displaying the zoomed in view. `Agrume` has a `statusBarStyle` property:\n\n```swift\nlet agrume = Agrume(image: image)\nagrume.statusBarStyle = .lightContent\nagrume.show(from: self)\n```\n\n### Long Press Gesture and Downloading Images\n\nIf you want to handle long press gestures on the images, there is an optional `onLongPress` closure. This will pass an optional `UIImage` and a reference to the Agrume `UIViewController` as parameters. The project includes a helper class to easily opt into downloading the image to the user's photo library called `AgrumePhotoLibraryHelper`. First, create an instance of the helper:\n\n```swift\nprivate func makeHelper() -\u003e AgrumePhotoLibraryHelper {\n  let saveButtonTitle = NSLocalizedString(\"Save Photo\", comment: \"Save Photo\")\n  let cancelButtonTitle = NSLocalizedString(\"Cancel\", comment: \"Cancel\")\n  let helper = AgrumePhotoLibraryHelper(saveButtonTitle: saveButtonTitle, cancelButtonTitle: cancelButtonTitle) { error in\n    guard error == nil else {\n      print(\"Could not save your photo\")\n      return\n    }\n    print(\"Photo has been saved to your library\")\n  }\n  return helper\n}\n```\n\nand then pass this helper's long press handler to `Agrume` as follows:\n\n```swift\nlet helper = makeHelper()\nagrume.onLongPress = helper.makeSaveToLibraryLongPressGesture\n```\n\n### Custom Overlay View\n\nYou can customise the look and functionality of the image views. To do so, you need create a class that inherits from `AgrumeOverlayView: UIView`. As this is nothing more than a regular `UIView` you can do anything you want with it like add a custom toolbar or buttons to it. The example app shows a detailed example of how this can be achieved.\n\n### Live Text Support\n\nAgrume supports Live Text introduced since iOS 16. This allows user to interact with texts and QR codes in the image. It is available for iOS 16 or newer, on devices with A12 Bionic Chip (iPhone XS) or newer.\n\n```swift\nlet agrume = Agrume(image: UIImage(named: \"…\")!, enableLiveText: true)\n```\n\n### Lifecycle\n\n`Agrume` offers the following lifecycle closures that you can optionally set:\n\n- `willDismiss`\n- `didDismiss`\n- `didScroll`\n\n### Running the Sample Code\n\nThe project ships with an example app that shows the different functions documented above. Since there is a dependency on [SwiftyGif](https://github.com/kirualex/SwiftyGif) you will also need to fetch that to run the project. It's included as git submodule. After fetching the repository, from the project's root directory run:\n\n```bash\ngit submodule update --init\n```\n\n## Licence\n\nAgrume is released under the MIT license. See LICENSE for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJanGorman%2FAgrume","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJanGorman%2FAgrume","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJanGorman%2FAgrume/lists"}