https://github.com/sukov/pagedmediaviewer
Elegant media display library, comparable to native Photos app, supporting both images and videos.
https://github.com/sukov/pagedmediaviewer
interactive-transition ios-photos media-viewer-library presentationcontroller swift swift-package-manager transition-animation uikit uipageviewcontroller uiviewcontrolleranimatedtransitioning uiviewcontrollerinteractivetransitioning uiviewcontrollertransitioningdelegate zooming-panning-moving
Last synced: 9 months ago
JSON representation
Elegant media display library, comparable to native Photos app, supporting both images and videos.
- Host: GitHub
- URL: https://github.com/sukov/pagedmediaviewer
- Owner: sukov
- License: mit
- Created: 2025-09-20T21:41:42.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-30T21:20:30.000Z (9 months ago)
- Last Synced: 2025-09-30T22:09:55.608Z (9 months ago)
- Topics: interactive-transition, ios-photos, media-viewer-library, presentationcontroller, swift, swift-package-manager, transition-animation, uikit, uipageviewcontroller, uiviewcontrolleranimatedtransitioning, uiviewcontrollerinteractivetransitioning, uiviewcontrollertransitioningdelegate, zooming-panning-moving
- Language: Swift
- Homepage:
- Size: 201 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PagedMediaViewer
[](https://cocoapods.org/pods/PagedMediaViewer)
[](https://cocoapods.org/pods/PagedMediaViewer)
[](https://swift.org)
[](https://cocoapods.org/pods/PagedMediaViewer)
[](https://www.swift.org/package-manager)
## Features
PagedMediaViewer is an elegant media display library, comparable to native Photos app, supporting both images and videos.
- [x] Smooth thumbnail-to-fullscreen interactive transition with return animation
- [x] Fullscreen display of any custom (media) view conforming to `PagedMediaItem` protocol
- [x] Configurable header, footer, and playback controls
- [x] Double tap & pinch to zoom with auto-hiding UI elements
- [x] Adjustable presentation insets to allow underlying views to remain visible (e.g. promotional content)
- [x] Comprehensive Unit & UI Test Coverage
- [x] [Complete Documentation](https://sukov.github.io/PagedMediaViewer/)
## Demo
| Image transition | Video transition & zoom | Media items pagination |
|:---:|:---:|:---:|
||||
The previews are from the example project. To run the example project, clone the repo, and run `pod install` from the Example directory first.
## Usage
### Quick Start
Check [PagedMediaViewControllerExample.swift](Example/PagedMediaViewer/PagedMediaViewControllerExample.swift) `PagedMediaDataSource` and `PagedMediaDelegate` implementation from the Example project.
### PagedMediaItem protocol
Media item to be presented in the PagedMediaViewController.
```Swift
public protocol PagedMediaItem: UIView {
/// Updates paused state depending on the transition status.
var paused: Bool { get set }
/// Whether the item is animated (video, gif, etc) or static (image, etc).
var isAnimated: Bool { get }
/// Used in the last part of the dismissal transition for animated items (if not `nil`) for smooth effect. Defaults to `nil`.
var animatedItemSnapshotAtCurrentTime: UIImage? { get }
/// Controls for play/pause and scrubbing. Defaults to `nil`.
var animatedItemControlsView: UIView? { get }
}
```
### PagedMediaDataSource protocol
Conform to `PagedMediaDataSource` to provide media items and customize their presentation.
```Swift
public protocol PagedMediaDataSource: AnyObject {
/// Number of items to be presented.
func numberOfItems(in pagedMediaViewController: PagedMediaViewController) -> Int
/// Adds insets on `PagedMediaViewController`'s view presentation frame. Defaults to `.zero`. Useful for preventing presentation over promotional content.
func presentationViewInsets(for pagedMediaViewController: PagedMediaViewController) -> UIEdgeInsets
/// Provides the media item view for the given index.
func pagedMediaViewController(_ pagedMediaViewController: PagedMediaViewController, pagedMediaViewForItemAt index: Int) -> PagedMediaItem
/// Provides the original view for the given index. Used for transition animations.
func pagedMediaViewController(_ pagedMediaViewController: PagedMediaViewController, originalViewForItemAt index: Int) -> UIView
/// Optional method for specifying the original image for the view or a snapshot. By default `PagedMediaTransitionDriver` will create a snapshot from the original view.
func pagedMediaViewController(_ pagedMediaViewController: PagedMediaViewController, transitionImageForItemAt index: Int) -> UIImage?
}
```
### PagedMediaDelegate protocol
Optional: Conform to `PagedMediaDelegate` for transition and item change events.
```Swift
public protocol PagedMediaDelegate: AnyObject {
/// Called just before the transition to a new item begins. Useful for centering table/collection view items behind the scenes for proper transition animation.
func pagedMediaViewController(_ pagedMediaViewController: PagedMediaViewController, willTransitionTo index: Int)
/// Called after the transition to a new item is completed.
func pagedMediaViewController(_ pagedMediaViewController: PagedMediaViewController, didTransitionTo toIndex: Int, fromIndex: Int)
/// Called just before the transition ends. Perfect time to unpause the original view at index.
func pagedMediaViewController(_ pagedMediaViewController: PagedMediaViewController,
willDismissToOriginalViewAt index: Int,
fromPagedMediaItem mediaItem: PagedMediaItem)
}
```
## Requirements
- iOS 13.0+
- Xcode 12.0+
- Swift 5.0+
## Installation
### CocoaPods
[CocoaPods](http://cocoapods.org) is a dependency manager for Cocoa projects. You can install it with the following command:
```bash
$ gem install cocoapods
```
To integrate PagedMediaViewer into your Xcode project using CocoaPods, specify it in your `Podfile`:
```ruby
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '13.0'
use_frameworks!
target '' do
pod 'PagedMediaViewer'
end
```
Then, run the following command:
```bash
$ pod install
```
### Swift Package Manager
The [Swift Package Manager](https://swift.org/package-manager/) is a tool for automating the distribution of Swift code and is integrated into the `swift` compiler.
Once you have your Swift package set up, adding `PagedMediaViewer` as a dependency is as easy as adding it to the `dependencies` value of your `Package.swift`.
```swift
dependencies: [
.package(url: "https://github.com/sukov/PagedMediaViewer.git", .upToNextMajor(from: "1.0.1"))
]
```
## Author
sukov, gorjan.shukov@gmail.com
## License
PagedMediaViewer is available under the MIT license. See the LICENSE file for more info.