KSImageCarousel is a lightweight image carousel which can easily adapt to different type of image source. KSImageCarousel support both finite and infinite scrolling mode. Just instantiate KSImageCarousel with your desire UIImages or image URLs and it will do all the work for you.
- Xcode 10 or later
- iOS 10.3 or later
- Swift 4.2 or later
- Infinite scrolling mode
- Finite scrolling mode
- Auto scroll
- Support
UIImage
andURL
as image source - Can easily adapt to other image source
Clone or download the source code and launch the project with KSImageCarouselExample.xcworkspace
. The example include sample code of using both infinite and finite scrolling mode.
pod 'KSImageCarousel'
- Create and update Cartfile
github "LeeKahSeng/KSImageCarousel"
- Build the framework using terminal
carthage update
- After finish building the framework using Carthage, open XCode and select you project in the project navigator.
- At
Build Phases
tab, addKSImageCarousel.framework
toLink Binary with Libraries
. - At
General
tab, addKSImageCarousel.framework
toEmbedded Binaries
.
- Download the project.
- Drag the
Sources
folder in\KSImageCarousel\KSImageCarousel
into your Xcode project. - Add
import UIKit
to all the source code that causing compile error. - Build & run.
KSImageCarousel is developed using coordinator pattern. Thus to start using KSImageCarousel, create a KSICInfiniteCoordinator
or KSICFiniteCoordinator
and use it to show the carousel in the desire container view.
Make sure you import KSImageCarousel if you are using CocoaPods or Carthage.
import KSImageCarousel
To use KSImageCarousel with finite scrolling mode.
// Create container view
let carouselContainer = UIView(frame: CGRect(x: 0, y: 0, width: 300, height: 150))
view.addSubview(carouselContainer)
// Create array of image source
let model = [
URL(string: "https://via.placeholder.com/375x281/403ADA/FFFFFF?text=Image-0")!,
URL(string: "https://via.placeholder.com/375x281/5D0F25/FFFFFF?text=Image-1")!,
URL(string: "https://via.placeholder.com/375x281/83B002/FFFFFF?text=Image-2")!,
URL(string: "https://via.placeholder.com/375x281/1B485D/FFFFFF?text=Image-3")!,
URL(string: "https://via.placeholder.com/375x281/E6581C/FFFFFF?text=Image-4")!,
]
// Use coordinator to show the carousel
if let coordinator = try? KSICFiniteCoordinator(with: model, placeholderImage: nil, initialPage: 0) {
coordinator.activityIndicatorStyle = .white
coordinator.showCarousel(inside: carouselContainer, of: self)
}
To use KSImageCarousel with infinite scrolling mode
// Create container view
let carouselContainer = UIView(frame: CGRect(x: 0, y: 0, width: 300, height: 150))
view.addSubview(carouselContainer)
// Create array of image source
let model = [
URL(string: "https://via.placeholder.com/375x281/403ADA/FFFFFF?text=Image-0")!,
URL(string: "https://via.placeholder.com/375x281/5D0F25/FFFFFF?text=Image-1")!,
URL(string: "https://via.placeholder.com/375x281/83B002/FFFFFF?text=Image-2")!,
URL(string: "https://via.placeholder.com/375x281/1B485D/FFFFFF?text=Image-3")!,
URL(string: "https://via.placeholder.com/375x281/E6581C/FFFFFF?text=Image-4")!,
]
// Use coordinator to show the carousel
if let coordinator = try? KSICInfiniteCoordinator(with: model, placeholderImage: nil, initialPage: 0) {
coordinator.activityIndicatorStyle = .white
coordinator.showCarousel(inside: carouselContainer, of: self)
}
To enable auto scrolling for KSICInfiniteCoordinator
coordinator.startAutoScroll(withDirection: .left, interval: 1)
To hide / show the activity indicator view when image being downloaded
coordinator.shouldShowActivityIndicator = true
To change the activity indicator view style
coordinator.activityIndicatorStyle = .white
Please note that both shouldShowActivityIndicator
and activityIndicatorStyle
needs to be set before calling showCarousel(inside: UIView, of: UIViewController)
To detect tap event on the carousel, just conform to KSICCoordinatorDelegate
and implement carouselDidTappedImage(at index: Int, coordinator: KSICCoordinator)
Feel free to clone or download the source code and checkout the KSImageCarouselExample project which highlights how to use KSImageCarousel correctly.
Currently KSImageCarousel support both UIImage
and URL
as image source. However, there might be situation where you need KSImageCarousel to support other image source such as Base64, byte array, etc., or you would prefer to use your project's own image downloader instead of the build-in downloader of KSImageCarousel. What you need to do is just create a custom image provider class and conform to KSImageCarouselDisplayable
protocol.
Sample class to support Base64 image source:
class Base64ImageProvider {
let base64: String
init(_ base64: String) {
self.base64 = base64
}
func covertToImage(completion: @escaping (UIImage?) -> Void) {
/*** Code to covert Base64 to UIImage here ***/
let convsionResult = UIImage()
/*********************************************/
// Call completion handler with the conversion result
completion(convsionResult)
}
}
extension Base64ImageProvider: KSImageCarouselDisplayable {
func createCarouselImage(completion: @escaping (UIImage?, KSImageCarouselDisplayable) -> Void) {
covertToImage { (image) in
completion(image, self)
}
}
func isEqual(to displayable: KSImageCarouselDisplayable) -> Bool {
if let provider = displayable as? Base64ImageProvider {
return base64 == provider.base64
} else {
return false
}
}
}
Sample class to use other image downloader:
class ImageProvider {
let url: URL
init(_ url: URL) {
self.url = url
}
func downloadImage(completion: @escaping (UIImage?) -> Void) {
/*** Code to download image using you own downloader class here ***/
let downloadResult = UIImage()
/******************************************************************/
// Call completion handler with the conversion result
completion(downloadResult)
}
}
extension ImageProvider: KSImageCarouselDisplayable {
func createCarouselImage(completion: @escaping (UIImage?, KSImageCarouselDisplayable) -> Void) {
downloadImage { (downloadedImage) in
completion(downloadedImage, self)
}
}
func isEqual(to displayable: KSImageCarouselDisplayable) -> Bool {
if let provider = displayable as? ImageProvider {
return url == provider.url
} else {
return false
}
}
}
This code is distributed under the terms and conditions of the MIT license.