✨ An elegant way to guide your beloved users in iOS apps - Material Showcase.

Overview

Material Showcase for iOS

Carthage compatible Download

An elegant and beautiful tap showcase view for iOS apps based on Material Design Guidelines.

Screenshots Screenshots

Requirement

  • iOS 10.0+
  • Swift 4.2+

Installation

CocoaPods

You can install it by using CocoaPods. Please add the following line to your Podfile.

pod 'MaterialShowcase'

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate MaterialShowcase into your Xcode project using Carthage, specify it in your Cartfile:

github "aromajoin/material-showcase-ios" ~> 0.8.0

Run carthage update to build the framework and drag the built MaterialShowcase.framework into your Xcode project.

Swift Package Manger

In the XCode, please select menu option "File" => "Swift Packages" => "Add package dependency..." Then, select the project you want to add the package, and enter this repository URL.

https://github.com/aromajoin/material-showcase-ios

Usage

Objective-C

In order to integrate the library into Object-C project, please follow the instructions from this doc.

Basic

  let showcase = MaterialShowcase()
  showcase.setTargetView(view: button) // always required to set targetView
  showcase.primaryText = "Action 1"
  showcase.secondaryText = "Click here to go into details"
  showcase.show(completion: {
    // You can save showcase state here
    // Later you can check and do not show it again
  })

Note: showcase.show() should be called after your views are placed correctly, for example inside UIViewController's viewWillAppear() or viewDidAppear() function. You SHOULD NOT call it inside viewDidLoad() because views have not laid down correctly yet, showcase can not calculate these views positions and it results in unexpected errors.

Supported target views

There are several target view supported.

  // Any UIView
  showcase.setTargetView(view: view)
  // UIBarButtonItem
  showcase.setTargetView(barButtonItem: barItem)
  // UITabBar item
  showcase.setTargetView(tabBar: tabBar, itemIndex: 0)
  // UItableViewCell
  showcase.setTargetView(tableView: tableView, section: 0, row: 0)

Enable TapThrough

By default, tapping a showcase's target does not perform it's predefined action. This can be overridden.

  // UIButton
  showcase.setTargetView(button: button, tapThrough: true)
  // UIBarButtonItem
  showcase.setTargetView(barButtonItem: barItem, tapThrough: true)
  // UITabBar item
  showcase.setTargetView(tabBar: tabBar, itemIndex: 0, tapThrough: true)

Handle showcase status

  // Right after showing.
  showcase.show(completion: {
    // You can save showcase state here
  })

  // To handle other behaviors when showcase is dismissing, delegate should be declared.
  showcase.delegate = self

  extension ViewController: MaterialShowcaseDelegate {
    func showCaseWillDismiss(showcase: MaterialShowcase, didTapTarget: Bool) {
      print("Showcase \(showcase.primaryText) will dismiss.")
    }
    func showCaseDidDismiss(showcase: MaterialShowcase, didTapTarget: Bool) {
      print("Showcase \(showcase.primaryText) dimissed.")
    }
  }

Dismiss showcase programmatically

  showcase.completeShowcase(animated: true, didTapTarget: false)

Support both LTR and RTL text alignment

In default, text aligment is set to be left-to-right. If you want to show text in right-to-left direction. Please define following.

showcase.primaryTextAlignment = .right
showcase.secondaryTextAlignment = .right

Dismiss showcase only if users click to target view

In default, showcase will be dismissed when users click to any place in whole showcase view. If you want to dismiss showcase only when users click to target view correctly, please set the following property.

showcase.isTapRecognizerForTargetView = true

Customize UI properties

You can define your own styles based on your app.

  // Background
  showcase.backgroundAlpha = 0.9
  showcase.backgroundPromptColor = UIColor.blue
  showcase.backgroundPromptColorAlpha = 0.96
  showcase.backgroundViewType = .full // default is .circle
  showcase.backgroundRadius = 300
  // Target
  showcase.targetTintColor = UIColor.blue
  showcase.targetHolderRadius = 44
  showcase.targetHolderColor = UIColor.white
  // Text
  showcase.primaryTextColor = UIColor.white
  showcase.secondaryTextColor = UIColor.white
  showcase.primaryTextSize = 20
  showcase.secondaryTextSize = 15
  showcase.primaryTextFont = UIFont.boldSystemFont(ofSize: primaryTextSize)
  showcase.secondaryTextFont = UIFont.systemFont(ofSize: secondaryTextSize)
  //Alignment
  showcase.primaryTextAlignment = .left
  showcase.secondaryTextAlignment = .left
  // Animation
  showcase.aniComeInDuration = 0.5 // unit: second
  showcase.aniGoOutDuration = 0.5 // unit: second
  showcase.aniRippleScale = 1.5
  showcase.aniRippleColor = UIColor.white
  showcase.aniRippleAlpha = 0.2
  //...

Sequence items

You can define showcase items and create sequence.

If you set key param sequence visible just one time or key is empty will always show be repeated

Always appear

  let sequence = MaterialShowcaseSequence()
  let showcase2 = MaterialShowcase()
  let showcase3 = MaterialShowcase()
  let showcase1 = MaterialShowcase()
  showcase1.delegate = self
  showcase2.delegate = self
  showcase3.delegate = self
  sequence.temp(showcase1).temp(showcase2).temp(showcase3).start()

Will appear once so we have key

  let sequence = MaterialShowcaseSequence()
  let showcase2 = MaterialShowcase()
  let showcase3 = MaterialShowcase()
  let showcase1 = MaterialShowcase()
  showcase1.delegate = self
  showcase2.delegate = self
  showcase3.delegate = self
  //Once the key value changes , it will appear once
  sequence.temp(showcase1).temp(showcase2).temp(showcase3).setKey(key: "temp").start()

Must extends MaterialShowCaseDelegate and This code into showCaseDidDismiss function

extension ViewController: MaterialShowcaseDelegate {
    func showCaseDidDismiss(showcase: MaterialShowcase, didTapTarget: Bool) {
        sequence.showCaseWillDismis()
    }
}

For more information, please take a look at sample app.

If you have any issues or feedback, please visit issue section. Please feel free to create a pull request.

Third Party Bindings

React Native

For React Native developers, you can use this library via its binding bridge created by @prscX.

NativeScript

For NativeScript developers, you can use this library via 3rd party plugin created by @hamdiwanis.

FAQ

Please check the FAQ page here.

License

Material Showcase is available under the Apache license. See the LICENSE file for more info.

Comments
  • How to increase the radius of colored background circle especially for iPads?

    How to increase the radius of colored background circle especially for iPads?

    I am trying to increase the size of the showcase to fit the device like it appears on iPhones but unable to find right option for that. Simulator Screen Shot - iPad Pro (12 9-inch) (3rd generation) - 2019-10-23 at 10 55 25

    I am trying to stretch the blue circle in the screenshot to be fit to the screen like it appears on the iPhone or at least be able to modify the size of it.

    Thank You :)

    feature-request 
    opened by pathaderavi-zz 14
  • Library not loaded: @rpath/libswiftUIKit.dylib

    Library not loaded: @rpath/libswiftUIKit.dylib

    Hi,

    When running a UI test outside Xcode, I get this error:

    Testing failed:
            Screenshots_MyApp:
                    Screenshots_MyApp-Runner.app (91451) encountered an error (Failed to load the test bundle. (Underlying error: The bundle “Screenshots_MyApp” couldn’t be loaded because it is damaged or missing necessary resources. The bundle is damaged or missing necessary resources. dlopen_preflight(/Users/me/Library/Developer/Xcode/Build/Products/Debug-MyApp-iphonesimulator/Screenshots_MyApp-Runner.app/PlugIns/Screenshots_MyApp.xctest/Screenshots_MyApp): Library not loaded: @rpath/libswiftUIKit.dylib
      Referenced from: /Users/me/Library/Developer/Xcode/Build/Products/Debug-MyApp-iphonesimulator/Screenshots_MyApp-Runner.app/PlugIns/Screenshots_MyApp.xctest/Frameworks/MaterialShowcase.framework/MaterialShowcase
      Reason: image not found))
    

    The solution for this problem is to add this line in your podspec:

    s.xcconfig = { 'ALWAYS_EMBED_SWIFT_STANDARD_LIBRARIES' => 'YES' }
    

    Please follow this report: https://github.com/airbnb/lottie-ios/issues/1141

    I was able to fix this by creating a fork and applying this flag manually.

    Thank you.

    opened by ppamorim 12
  • MaterialShowCaseSequence Not Present

    MaterialShowCaseSequence Not Present

    Hi I am currently working in an application which needs multiple showcases shown in an sequence (just like the example shown in the ReadMe ) however I cannot find that option can you please help

    opened by deepskandpal 12
  • TapThrough Functionality

    TapThrough Functionality

    Let me know if this needs more explanation.

    Also, I did make changes to the sample app on my local machine to test this out, but didn't necessarily want to include them. Let me know if you'd want to see how I tested, or if you have trouble testing yourself.

    opened by poisondminds 11
  • overlapping texts

    overlapping texts

    Hi @quangctkm9207

    Thanks for such an handy library. I tried using this library which works like charm but i have a problem with it, this is kinda wierd but sometimes (it doesn't follow a certain pattern)sometimes when the user see's the showcase the text is kinda overlapped check the pic bellow. i dont know why this happens :
    it's like the showcase is showing two of the showcase at the same time but whit diffrent positions 1537784143137

    opened by benjimkh 11
  • Thread 1: Fatal error: Unexpectedly found nil while unwrapping an Optional value at: let center = calculateCenter(at: targetView, to: containerView)

    Thread 1: Fatal error: Unexpectedly found nil while unwrapping an Optional value at: let center = calculateCenter(at: targetView, to: containerView)

    Hey I have a while implementing this pod, and recently this problem starts to show up. First I think that was a problem of mine, that maybe I delete my variable or image where was attached, at end few times works and rest no.

    Always launching an error (Fatal error: Unexpectedly found nil while unwrapping an Optional value) in:

    func initViews() {
        let center = calculateCenter(at: targetView, to: containerView)
        
        addTargetRipple(at: center)
        addTargetHolder(at: center)
        addTarget(at: center)
        addInstructionView(at: center)
        instructionView.layoutIfNeeded()
        addBackground()
    
        // Add gesture recognizer for both container and its subview
        addGestureRecognizer(tapGestureRecoganizer())
        // Disable subview interaction to let users click to general view only
        for subView in subviews {
          subView.isUserInteractionEnabled = false
        }
      }
    
    invalid 
    opened by GeekerX 10
  • First time showing showcase repeats long texts with overlap!

    First time showing showcase repeats long texts with overlap!

    Hi, I am using showcase first time app opens. My problem is when the showcase texts are long, they repeated and overlapped on each other (I one show case the secondary text or primary text repeated and overlapped on itself). If i close the app and restart It again this problem does not occur. The weird thing is I couldn't repeat the problem in the demo application.

    Note: I tested and the problem occur in both English and Persian languages.

    img_6269

    Here is my code :

     override func viewDidAppear(_ animated: Bool) {
            super.viewDidAppear(animated)
            self.showHelp()
    }
    
    private func showHelp() {
            let userDefaults = UserDefaults.standard
            let helpShowed = userDefaults.value(forKey: "HELP_MENU") as? Bool ?? false
            if !helpShowed {
                let showCaseLogin = MaterialShowcase()
                showCaseLogin.setTargetView(tableView: self.tableView, section: 1, row: 1)
                showCaseLogin.backgroundPromptColorAlpha = 0.85
                showCaseLogin.primaryTextAlignment = .right
                showCaseLogin.secondaryTextAlignment = .right
                showCaseLogin.backgroundPromptColor = Colors.GRAY_BLUE_DARK_COLOR!
                showCaseLogin.primaryTextFont = Fonts.font(.IRANSans_Medium_fa, 20.0)
                showCaseLogin.secondaryTextFont = Fonts.font(.IRANSans_UltraLight_fa, 16.0)
                showCaseLogin.primaryText = "پروفایل شخصی"
                showCaseLogin.secondaryText = "امکان مشاهده سوابق نیکوکاری، صندوق های صدقات و امکانات دیگر برای کاربرانی که ثبت نام نموده باشند."
                showCaseLogin.show {
                    userDefaults.set(true, forKey: "HELP_MENU")
                    userDefaults.synchronize()
                   
                }
            }
        }
    
    opened by hrsalehi 8
  • Not TargetHolderView to be Rectangle for UITableViewCell

    Not TargetHolderView to be Rectangle for UITableViewCell

    Hi @quangctkm9207

    Thanks for such an handy library. I tried using this library which works like charm but when I add it to custom tableView, I am not able to get the actual effect of Showcase in Rectangle. (Though its working fine if defined the radius , but then it shows in TargetHolderView in Circle)

    Below is the code snippet :

    class func showShowcaseForTableSection(tableview : UITableView, viewController : UIViewController,  showcasetype : ShowCaseType, section: Int, row: Int){
            
            let showcase = MaterialShowcase()
            showcase.setTargetView(tableView: tableview, section: section, row: row)
            showcase.primaryText = showcasetype.primaryText
            showcase.secondaryText = ""
    //        showcase.targetHolderRadius = 80 // Just need to ignore this, as I was rectangle targetHolder
    //        showcase.targetHolderColor = UIColor.white
            showcase.shouldSetTintColor = false // Tried using this as well as
            showcase.backgroundPromptColor = UIColor.darkHotPink
            showcase.isTapRecognizerForTagretView = false
            showcase.delegate = viewController as? MaterialShowcaseDelegate
            showcase.show(completion: { DataManager.sharedInstance.tutorialStepsCounter += 1 })
        }
    

    Can you help me out where I am making the mistake or I doubt, if this gonna work with custom tableViewCells too.

    opened by ajaysharmalike 8
  • iOS 10 target placement issue

    iOS 10 target placement issue

    I am seeing this in iOS 10 - It may exist in other versions, but it was just reported by a users. The target placement is placed in the wrong location and button highlighting seems to be incorrect as well.

    simulator screen shot - ipad pro 12 9 inch - 2018-05-19 at 09 12 57

    opened by jamespet77 8
  • [Request][Feature] Add GOT IT/SKIP button for skipping sequences

    [Request][Feature] Add GOT IT/SKIP button for skipping sequences

    Hi @quangctkm9207, This lib will be better if the sequence case has skip button/text with style define like setDismissText, setDismiss Button radius,...

    => In case user can break/skip tutorial sequences :)

    Thanks, Cong

    feature-request 
    opened by congnguyen91 8
  • Click event on showcase

    Click event on showcase

    Hi, I have one question How can i check event click for example when showcase show first tab item after user click on it I want to show next tab item as show case. How can I do this? Another question is how can I change default background color of circle?

    Thanks, vafa

    enhancement question 
    opened by vre142 8
  • MaterialShowcase.swift line 119 MaterialShowcase.setTargetView(view:)

    MaterialShowcase.swift line 119 MaterialShowcase.setTargetView(view:)

    Crashes in crashlytics dashboard with the following error:

    Crashed: com.apple.main-thread EXC_BREAKPOINT 0x00000001006503d4

    Crashed: com.apple.main-thread 0 nws 0xf43d4 MaterialShowcase.setTargetView(view:) + 119 (MaterialShowcase.swift:119) 1 nws 0xf4410 @objc MaterialShowcase.setTargetView(view:) + 327180 (:327180) 2 nws 0xf19cc -[RNAppTour generateMaterialShowcase:props:] + 260 (RNAppTour.m:260) 3 nws 0xf1040 -[RNAppTour ShowFor:props:] + 122 (RNAppTour.m:122) 4 nws 0xf0fb0 -[RNAppTour ShowSequence:props:] + 117 (RNAppTour.m:117) 5 nws 0xf1e68 -[RNAppTour showCaseDidDismissWithShowcase:didTapTarget:] + 298 (RNAppTour.m:298) 6 nws 0xf830c MaterialShowcase.completeShowcase(animated:didTapTarget:) + 343304 (:343304) 7 nws 0xf86fc @objc MaterialShowcase.completeShowcase(animated:didTapTarget:) + 344312 (:344312) 8 nws 0xf8038 @objc MaterialShowcase.tapGestureSelector(tapGesture:) + 342580 (:342580) 9 UIKitCore 0x1df8f0 -[UIGestureRecognizerTarget _sendActionWithGestureRecognizer:] + 56 10 UIKitCore 0x1a8a24 _UIGestureRecognizerSendTargetActions + 116 11 UIKitCore 0x171770 _UIGestureRecognizerSendActions + 284 12 UIKitCore 0x1aadd4 -[UIGestureRecognizer _updateGestureForActiveEvents] + 636 13 UIKitCore 0x162fe0 _UIGestureEnvironmentUpdate + 1988 14 UIKitCore 0x196d8c -[UIGestureEnvironment _updateForEvent:window:] + 784 15 UIKitCore 0x1a3f2c -[UIWindow sendEvent:] + 4428 16 UIKitCore 0x353e34 -[UIApplication sendEvent:] + 828 17 UIKitCore 0x177140 __dispatchPreprocessedEventFromEventQueue + 7904 18 UIKitCore 0x16bf2c __processEventQueue + 6760 19 UIKitCore 0x1713d8 __eventFetcherSourceCallback + 172 20 CoreFoundation 0xbb0d0 CFRUNLOOP_IS_CALLING_OUT_TO_A_SOURCE0_PERFORM_FUNCTION + 28 21 CoreFoundation 0xcbd90 __CFRunLoopDoSource0 + 208 22 CoreFoundation 0x6098 __CFRunLoopDoSources0 + 268 23 CoreFoundation 0xb8a4 __CFRunLoopRun + 820 24 CoreFoundation 0x1f468 CFRunLoopRunSpecific + 600 25 GraphicsServices 0x138c GSEventRunModal + 164 26 UIKitCore 0x5195d0 -[UIApplication _run] + 1100 27 UIKitCore 0x297f74 UIApplicationMain + 364 28 nws 0x6164 main + 7 (main.m:7) 29 ??? 0x100e85aa4 (Missing)

    Devices Details:

    Model:iPhone XR Orientation: Portrait

    Operating System Version:15.3.1 Orientation: Portrait Jailbroken: No

    opened by Murugeshrockey-RN 0
  • SwiftUI using

    SwiftUI using

    Hello there! I really like your library and I would like to use it on my SwiftUI app. Can you expose a method to pass to setTargetView a View instead of a UIView? I'm trying to achieve it using a UIHostingController in this way:

    let showcase = MaterialShowcase()
    let hc = UIHostingController(rootView: mySwiftUIView)
    hc.view.frame = CGRect(x: 100, y: 200, width: 200, height: 100)
    showcase.setTargetView(view: hc.view)
    showcase.show(completion: {
        print("Showcase completion!")
    })
    

    But would be very useful if you can expose that method! Thanks!

    opened by Spettacolo83 6
  • Showcase view not dismissing if we push a view controller when it is displaying

    Showcase view not dismissing if we push a view controller when it is displaying

    Hi I am using showcase for displaying help text for user first time login.But I am facing few issues in iOS 12 version. I am presenting a showcase and meanwhile if get a notification I will navigate to another screen.After dismissing from Second Viewcontroller If I tap on screen showcaseview next sequeence is showing.

    I am not sure how to kill the showcase view instance completely.

    opened by bejgumshirisha 0
Owner
Aromajoin
We develop the finest digital scent products based on the harmony of hardware, software and material technology.
Aromajoin
iOS library Paper Onboarding is a material design UI slider written on Swift.

iOS library Paper Onboarding is a material design UI slider written on Swift. We specialize in the designing and coding of custom UI

Ramotion 3.2k Jan 5, 2023
A simple and attractive AlertView to onboard your users in your amazing world.

AlertOnboarding A simple and attractive AlertView to onboard your users in your amazing world. PRESENTATION This AlertOnboarding was inspired by this

Boisney Philippe 832 Jan 8, 2023
SuggestionsKit is a framework for iOS that was created in order to provide developers with the opportunity to educate users on various features of applications.

SuggestionsKit is a framework for iOS that was created in order to provide developers with the opportunity to educate users

Ilya 63 Nov 30, 2022
SwiftyWalkthrough is a library for creating great walkthrough experiences in your apps, written in Swift.

SwiftyWalkthrough is a library for creating great walkthrough experiences in your apps, written in Swift. You can use the library to allow users to navigate and explore your app, step by step, in a predefined way controlled by you.

Rui Costa 370 Nov 24, 2022
WVWalkthroughView is an objective C based utility to highlight certain parts for iOS apps.

WVWalkthroughView A simple utility written in Objective C to help developers walk a user through their app. It allows a message to be displayed, a par

Praagya Joshi 29 Mar 25, 2021
Create walkthroughs and guided tours (coach marks) in a simple way, with Swift.

Add customizable coach marks into your iOS project. Available for both iPhone and iPad. ⚠️ Instructions 2.0.1 brings a couple of breaking changes, ple

Frédéric Maquin 4.9k Jan 3, 2023
BWWalkthrough is a simple library that helps you build custom walkthroughs for your iOS App

What is BWWalkthrough? BWWalkthrough (BWWT) is a class that helps you create Walkthroughs for your iOS Apps. It differs from other similar classes in

Yari @bitwaker 2.8k Jan 4, 2023
OnboardKit - Customizable user onboarding for your UIKit app in Swift

OnboardKit Customizable user onboarding for your UIKit app in Swift Requirements Swift 5.0 Xcode 10 iOS 11.0+ Installation Carthage github "NikolaKire

Nikola Kirev 470 Dec 23, 2022
A swifty iOS framework that allows developers to create beautiful onboarding experiences.

SwiftyOnboard is being sponsored by the following tool; please help to support us by taking a look and signing up to a free trial SwiftyOnboard A simp

Juan Pablo Fernandez 1.2k Jan 2, 2023
An iOS framework to easily create a beautiful and engaging onboarding experience with only a few lines of code.

Onboard Click Here For More Examples Important Onboard is no longer under active development, and as such if you create any issues or submit pull requ

Mike 6.5k Dec 17, 2022
A simple keyframe-based animation framework for iOS, written in Swift. Perfect for scrolling app intros.

RazzleDazzle is a simple AutoLayout-friendly keyframe animation framework for iOS, written in Swift. Perfect for scrolling app intros. RazzleDazzle gr

IFTTT 3.4k Jan 1, 2023
Fully customisable tooltip view in Swift for iOS.

Description EasyTipView is a fully customizable tooltip view written in Swift that can be used as a call to action or informative tip. Contents Featur

Teo 2.9k Dec 27, 2022
An iOS framework to easily create simple animated walkthrough, written in Swift.

Intro Overview An iOS framework to easily create simple animated walkthrough, written in Swift. Requirements iOS8 Installation with CocoaPods Intro is

Nurdaulet Bolatov 33 Oct 1, 2021
A longstanding annoying bug in our beloved operating system macOS

Houston There is a longstanding annoying bug in our beloved operating system macOS. If you open an application while Mission Control is active, the ap

Christoffer Winterkvist 6 Dec 5, 2022
Guide users through your SwiftUI app with coach marks

Guide users through your SwiftUI app with coach marks

Jake Heiser 15 Nov 22, 2022
A platform to showcase your side projects/apps

A platform to discuss/showcase your side projects What is this? Inspired by this twitter thread Indie Apps Showcases is a platform for indie app devel

An Tran 25 Dec 27, 2022
ReleaseNotesKit - a brand new, elegant, and extremely simple way to present the recent version’s release notes to your users

ReleaseNotesKit This is ReleaseNotesKit, a brand new, elegant, and extremely simple way to present the recent version’s release notes to your users. R

Swapnanil Dhol 22 Jun 30, 2022
Jorge Ovalle 305 Oct 11, 2022
FSPagerView is an elegant Screen Slide Library. It is extremely helpful for making Banner View、Product Show、Welcome/Guide Pages、Screen/ViewController Sliders.

SWIFT OBJECTIVE-C FSPagerView is an elegant Screen Slide Library implemented primarily with UICollectionView. It is extremely helpful for making Banne

Wenchao Ding 6.7k Jan 2, 2023
Pendo captures product usage data, gathers user feedback, and lets you communicate in-app to onboard, educate, and guide users to value

Pendo SDK for IOS The Pendo Mobile SDK is a code-less, retro-active analytics collector across all of your app's versions. The SDK also allows present

Pendo 30 Jan 4, 2023