Using Facebook Shimmer with Swift

Using Facebook Shimmer with Swift


If you’re an iOS user, then you’ve definitely seen the fancy “slide to unlock” shimmering control on iOS. And if you’ve seen it, then you’ve probably wanted to simulate the same effect in a control yourself. If you haven’t had the time to spend coming up with the right animation sequence, or didn’t know where to begin, this tutorial is for you :]

Here’s the good news: Facebook also really liked this effect and decided to include it in its app, Paper. Not only that, the developers also released the code on GitHub as the Shimmer library, so you to could use the effect in your own projects!

In this tutorial, you’ll learn:

  • How to use Facebook’s Shimmer library via CocoaPods in a simple clock application.
  • How to implement Shimmer in Swift with minimal coding by using a bridging header.
  • How to set up the controls to configure timing, direction, and other fine details.

This tutorial assumes you have a properly installed version of CocoaPods and some familiarity in using it. If you haven’t had any experience with CocoaPods, you can follow Introduction to CocoaPods 2 to get up to speed.

Another resource you should be familiar with is the CocoaPods home page.

Getting Started

It’s refreshingly straightforward to add Facebook Shimmer to your application. In this tutorial, you’ll add Shimmer to a simple clock application named SparkleClock – everybody knows that a digital clock without shimmer is a clock without character. So, we’ll sparkle it up!

Shimmer’s main component is FBShimmeringView, a UIView subclass. Once you add an instance of FBShimmeringView to the view hierarchy, you simply set a specific UIView as the contentView. This is the view that will start shimmering based on how you configure things.

It’s really that simple.

Facebook built in a lot of knobs and levers you can play with, and this tutorial covers some of the fun you can have with these controls later on in the tutorial.

Making SparkleClock Shimmer

Download the SparkleClock starter project from here. Expand the ZIP file, and move it into a directory you’ll be able to find easily. Launch Xcode, and then open SparkleClock.xcodeproj.

SparkleClock is a very simple application. It has a single view controller, a UILabel instance that displays the time, an NSTimer to update the label, an NSDateFormatter for localized time display, and a tap gesture recognizer.

The UI is already set up using autolayout and the IBOutlets are all set – it’s ready to run right out of the box! Build and run to see your working clock.

SparkClock Non-Shimmering

Okay, it works, but it’s just an ordinary clock. The kind of app that is almost a rite of passage for new developers – they are a dime a dozen in the App Store. However, once you add shimmer to it, you’ll make this app more unique, and thus more appealing.

The first step is to install Facebook Shimmer via CocoaPods.

Create a new file by selecting File\New\File… and select iOS\Other\Empty. Click Next. Enter Podfile as the filename in Save As and make sure you’re in the project’s root directory (where SparkleClock.xcodeproj is). Click Create.

Add the following text to Podfile:

source ''
platform :ios, '8.0'

pod 'Shimmer'

Close Xcode project via File\Close Project.

Run Terminal by opening Spotlight and typing terminal. Next, navigate to the directory where you saved the SparkleClock project (the folder containing SparkleClock.xcodeproj) by typing cd “The path to your project folder” and press enter.

Pro tip: In Terminal, first type cd followed by a space, and then drag and drop the icon for your project folder into the Terminal right next to the cd. Terminal should automatically add the full path to the project directory.

Still in Terminal, install the Facebook Shimmer dependency by typing pod install and press enter. The output should look something like this:

$ pod install
Analyzing dependencies
Downloading dependencies
Installing Shimmer (1.0.2)
Generating Pods project
Integrating client project

[!] From now on use `SparkleClock.xcworkspace`.

Open the newly created workspace by simply double-clicking SparkleClock.xcworkspace in Finder. Alternatively, you can select File\Open… in the Xcode menu, select SparkleClock.xcworkspace, and then click Open.

The Code

Since this application is primarily in Swift and Facebook Shimmer is an Objective-C library, you need to add a bridging header which lets Swift know about the Objective-C classes that you’ll be working with.

Select the SparkleClock group under the project root in the Project Navigator (press Command-1 if it’s not showing), select File\New\File… from the menu, and then select iOS\Source\Header File. Click Next, name the file SparkleClock-Bridging-Header.h and click Create.

Replace the contents of the new file with the following:


Next, select the project root in the Project Navigator, and then select the SparkleClock target.

Choose the Build Settings tab, and find the Swift Compiler – Code Generation\Objective-C Bridging Header item. As a shortcut, you can type bridging in the search field at the top of the settings to find the item quickly.

Double-click the value field to the right of the Objective-C Bridging Header label and enter the location of the bridging header that you just created: SparkleClock/SparkleClock-Bridging-Header.h.

Note: If you saved the bridging header file to a different location, or if you get the location wrong above, when you build the project later you’ll get errors. So make sure that the location you enter above is correct.

Okay, almost there! All you’ve done so far is to add the Shimmer library to the project and set a bridging header up so that your Swift code can work with the Shimmer library, which is in Objective-C. Now comes the fun part – implementing the Shimmer functionality.

Select ViewController.swift and add another IBOutlet at the top of the file as follows:

@IBOutlet var shimmeringView: FBShimmeringView!

The above outlet will point to the Shimmer subview.

Add the following two lines to the end of viewDidLoad:

shimmeringView.contentView = clockLabel
shimmeringView.shimmering = true

The new lines set up the Shimmer view by pointing to the content view for the Shimmer view and enabling shimmering.

Finally, add this line to the beginning of didTapView:

shimmeringView.shimmering = !shimmeringView.shimmering

This code toggles the shimmer effect on and off each time the user taps the view.

That’s all there is to set up the Shimmer library via code. Simple, right?

But hold on, you’re not done yet :] Remember the new outlet we setup a little while ago? Did you find yourself asking, “Where is the view for that outlet?” If you did, you’ll get the answer next.

The Storyboard

Select Main.storyboard in the Project Navigator. This is where you’ll set up the FBShimmeringView outlet.

Expand the Document Outline so that you can see the full view hierarchy for the View Controller scene. Then, select the subview under the main view.

Then, switch to the Identity Inspector (press Option-Command-3 to show) and set the Class under Custom Class to FBShimmeringView.

Next, select View Controller in the Document Outline and switch to the Connections Inspector (press Option-Command-6 to show). Find the shimmeringView outlet and connect it to the subview you just modified by dragging from the plus sign to the subview.


That’s it, the bulk of the work is done!

Build and run the project to see your cool shimmering clock.


Tapping on the clock starts and stops the shimmering effect. However, the shimmering effect is a little offbeat; it’s not synchronized with the ticking by of the seconds. Timing is one of the many variables you can tweak to achieve the perfect effect, and this tutorial will discuss the various values you can configure, in a bit.

Note: The view you want to shimmer doesn’t have to be a subview of the FBShimmeringView. Whatever view you assign to shimmeringView.contentView becomes shimmery.

One easy way to verify this is to modify Main.storyboard by moving the UILabel so it’s outside of the view hierarchy, as shown here:


Build and run, and you’ll see that everything still works just as before.

It’s this line below that sets the content view for the Shimmer effect.:

shimmeringView.contentView = clockLabel

You can modify that line to point to any view that you want to use as the content view.

How Shimmer Works

How exactly does Shimmer work? Is it magical micro-sized leprechauns inside the phone throwing pixie dust on everything to make it glitter? Or, PPerhaps a mystical unicorn flew over while you were coding and imbued the device with sparkliness?

Actually, there’s no magic involved at all: Shimmer uses a small set of components to produce the shimmering effect you see.

There are four main components to Shimmer:

  1. FBShimmering protocol
  2. FBShimmeringView (a UIView subclass)
  3. FBShimmeringLayer (a CALayer subclass)
  4. FBShimmeringMaskLayer (a CAGradientLayer subclass)

The FBShimmering protocol defines the list of properties that all shimmering views should have – all of these variables are discussed in the next section of this tutorial. FBShimmeringView and FBShimmeringLayer both implement this protocol. You can view these files in the Shimmer GitHub repository.

FBShimmeringView is a lightweight class that acts as manager for the view you want to shimmer. It implements the actual shimmering.

FBShimmeringView has a property named contentView that you use to specify the view you want to shimmer. The contentView setter method adds your view as a subview and saves a reference to the subview’s CALayer to use when shimmering.

FBShimmeringView uses a set of preprocessor macros to set up all of the property accessors and mutators to conform to the FBShimmering protocol. All of the properties on FBShimmeringView simply pass forward the values to the underlying FBShimmeringLayer.

All the magic happens in FBShimmeringLayer. The effect is simply an animated change of gradient colors that fade in the FBShimmeringMask layer. Core Animation drives all of this. If you look at the _updateShimmering method near the end of FBShimmeringLayer.m, you’ll see animations being created and timing being established. At the top of FBShimmeringLayer.m there are a handful of static methods that construct the individual animations used throughout the CALayer subclass.

Most of the rest of the code is there to handle the somewhat complex layout math that runs all of the moving pieces.

Even if you don’t fully understand the math and timings of all of the animations, there is one big take-away: someone took a lot of time to get the feel of the animations right and it was likely an iterative process. Learn to use the variables to change the timings and see what effect each one has on FBShimmeringLayer.

All the Variables

Here’s a list of all the properties you can configure via the FBShimmering protocol that’s used by Shimmer.


  • Default value: 0.4 seconds
  • Adds length to the gradient to give additional time.


  • Default value: 0.5 (1.0 is opaque)
  • Used on the unmasked color in the CAGradientLayer.


  • Default value: 1.0 (1.0 is opaque)
  • Used on the masked color in the CAGradientLayer.


  • Default value: 230 (arbitrary scale)
  • This changes the speed of the shimmer; a lower number means a faster shimmer. You use this in combination with pause duration.


  • Default value: 1.0
  • A value between 0.0 and 1.0 that determines the position locations of the CAGradientLayer.


The possible values for this property as defined in the library code (in Objective-C) are:

typedef NS_ENUM(NSInteger, FBShimmerDirection) {
FBShimmerDirectionRight, // Shimmer animation goes from left to right
FBShimmerDirectionLeft, // Shimmer animation goes from right to left
FBShimmerDirectionUp, // Shimmer animation goes from below to above
FBShimmerDirectionDown, // Shimmer animation goes from above to below

Default value: FBShimmerDirectionRight

However, when imported into Swift the above enumeration becomes:

enum FBShimmerDirection: Int {
case Right
case Left
case Up
case Down

So, while you would write the following in Objective-C:

shimmeringView.shimmeringDirection = FBShimmerDirectionLeft;

In Swift you would write:

shimmeringView.shimmeringDirection = FBShimmerDirection.Left

To learn more about this, take a look at Apple’s guide on Interacting with C APIs.


  • Default value: 0.1 seconds
  • The amount of time taken to fade in.


  • Default value: 0.3 seconds
  • The amount of time taken to fade out.

Add the following to the end of viewDidLoad and experiment with changing the values if you’d like to see how these values affect the shimmer effect.

//Optional ShimmeringView protocal values
    //All values shown are the defaults
    shimmeringView.shimmeringPauseDuration = 0.4
    shimmeringView.shimmeringAnimationOpacity = 0.5
    shimmeringView.shimmeringOpacity = 1.0
    shimmeringView.shimmeringSpeed = 230
    shimmeringView.shimmeringHighlightLength = 1.0
    shimmeringView.shimmeringDirection = FBShimmerDirection.Right
    //All possible directional values
    //FBShimmerDirection.Right,  Shimmer animation goes from left to right
    //FBShimmerDirection.Left,  Shimmer animation goes from right to left
    //FBShimmerDirection.Up,  Shimmer animation goes from below to above
    //FBShimmerDirection.Down,  Shimmer animation goes from above to below
    shimmeringView.shimmeringBeginFadeDuration = 0.1
    shimmeringView.shimmeringEndFadeDuration = 0.3

Where To Go From Here

Adding a shimmer effect to your application is extremely simple with Facebook Shimmer. The library is easy to use, and though it’s written in Objective-C, it plays nicely with Swift.

Try changing the values of the various protocol properties and see what happens. Can you make the shimmer happen once for every passing second?

Also, you can use Shimmer on more than just labels. It might add a nice effect in other places as well. For instance, how about shimmering eyes or a lake that shimmers?

Finally, it might be worth noting that while this tutorial used a storyboard, you can implement the Shimmer effect totally in code as well. You could try to implement the whole thing in code as an additional challenge and see how you do :]

Here’s the final project source code. Be sure to open SparkleClock.xcworkspace and NOT SparkleClock.xcodeproj.

Thanks for taking the time to work through this tutorial. Shimmer is a small enhancement that elevates your UI and adds polish to your work. Now you know the secrets of adding shimmer to any apps you make. Furthermore, you know how to control it so the effect looks really sharp.

Feel free to chime in on the forums below if you have questions, comments, or just want to show off how you implemented shimmer in your own app. I look forward to hearing from you!

Using Facebook Shimmer with Swift is a post from: Ray Wenderlich

The post Using Facebook Shimmer with Swift appeared first on Ray Wenderlich.



Write a comment