Introducing RIGImageGallery

RIGImageGallery is a component from the Raizlabs Interface Guidelines, which is a set of UI components that offer sensible defaults to help a project get off the ground quickly and feel native to the platform, and with easy-to-use customization options.

RIGImageGallery is designed to display a gallery of images with the expected behaviors established by the iOS system Photos app, and to make it easy to customize its behavior and style. RIGImageGallery is freely available under the MIT license on GitHub.

RIGImageGallery in action, showing presentation, paging, and zooming

Using the Gallery

To use the image gallery, create an array of images to display:

Then, create a RIGImageGalleryViewController with that set of images, and present it:

Asynchronous Loading

The gallery will reload content whenever the images property is changed, and because it’s an array of value types, “changed” includes any time the array has a value inserted or removed and any time a property of an item in the array is changed. Let’s demonstrate this by expanding the example above to load images from a server and display placeholders during loading:

This updates the array each time an image successfully loads, and updates the placeholder if you are currently looking at it when its image loads.

Customizing the Gallery

There is a series of optional closure properties for you to customize handling of certain events. Here are a few of the customizations available:

If the dismiss handler is nil, then the Done button button will dismiss the image gallery controller, but that behavior can be changed by supplying a (RIGImageGalleryViewController) -> () closure to the dismissHandler property. If that closure is supplied, it is responsible for dismissing the gallery view.

To add an action button, set the actionButton property to a non-nil UIBarButtonItem, and then set the actionButtonHandler property to a closure with a signature of ( RIGImageGalleryViewController, RIGImageGalleryItem) -> (). This closure is executed when the action button is tapped.

To control how the gallery responds to trait collection changes, in particular to allow the Done button to be hidden, for instance to allow the photo gallery should support rotation without the view controller presenting the image gallery supporting rotation, set the traitCollectionChangeHandler to a (RIGImageGalleryViewController) -> () closure.

To handle changes to the number of items in the gallery, or the position of the image in the updated set to display, the countUpdateHandler accepts a (RIGImageGalleryViewController, _ position: Int, _ total: Int) -> () closure.

What’s Next?

The next feature we plan to add is a swipe-down-to-dismiss gesture recognizer that matches the interactive dismissal of the system Photos app. If you’d like to help out, we’ll gladly accept pull requests!

Do you have a project in mind? We’d love to work with you. If you’d like an opportunity to work on projects with us, check out our Careers page. We’re hiring!

Leave a Comment