What is backIndicatorTransitionMaskImage


In the last article, How to change a back button image, we learn that to set a custom back button indicator, we have to set an image to both backIndicatorImage and backIndicatorTransitionMaskImage.

From backIndicatorImage documentation:

If you want to customize the back indicator image, you must also set backIndicatorTransitionMaskImage.

From backIndicatorTransitionMaskImage documentation:

If you want to customize the back indicator image, you must also set backIndicatorImage.

So, you end up assigning the same image to both properties.

UINavigationBar.appearance().backIndicatorImage = UIImage(named: "custom-back")
UINavigationBar.appearance().backIndicatorTransitionMaskImage = UIImage(named: "custom-back")

These two properties serve a different purpose. For backIndicatorImage, it quite obvious. It serves as an image for the back button. So, what is the purpose of backIndicatorTransitionMaskImage?

backIndicatorTransitionMaskImage #

As a name imply, backIndicatorTransitionMaskImage use as masking for content that flowing under the back indicator image during push and pop transitions. It is clearer to see this in action than reading.

Here is the default behavior of the native UINavigationController.

Default transition animation
Default transition animation

You might not know where to looks at. Here is the snapshot of backIndicatorTransitionMaskImage in action.

Default transition animation
Default transition animation

As you can see, the text is sliding in and out from the right edge of the arrow shape.

Replication #

Let's try to set a similar image and see what happens. Here is our custom arrow image.

And here is our transition animation.

Transition animation for custom image
Transition animation for custom image

As you can see, the text shows up at the end of our image frame, not the edge of the arrow, as the default behavior.

The proper way to mask #

First, let's revisit the meaning of the mask image before we jump to the solution.

In the mask image:

  • The opaque pixels (alpha = 1, a black area in our case) will be visible for the moving title during navigation transitions.
  • The transparent pixels will be covering the moving title during navigation transitions.

So, to provide the same effect as in the native back indicator, you have to use a different image for your mask (backIndicatorTransitionMaskImage).

Here is the image that you should use.

We fill the right part of the arrow with opaque color (black), so the text will be visible during the animation.

Transition animation for custom image
Transition animation for custom image

Our mask now works the same way as the native one.

Caveat #

You might notice that text isn't properly masked as we might be expected. Some text is visible on the left part of the arrow.

Some text still visible on the left of the arrow
Some text still visible on the left of the arrow

To mitigate this, you should offset your mask a bit.

Our back indicator (Left), Mask that causes the trouble (Middle), and Mask that you should use (Right)
Our back indicator (Left), Mask that causes the trouble (Middle), and Mask that you should use (Right)

Conclusion #

This is such a subtle animation that you can easily get away with since nobody likely to notice it, but if you have a little bit of time and resources, this hassle will definitely please your designers.


Feel free to follow me on Twitter and ask your questions related to this post. Thanks for reading and see you next time.

If you enjoy this article, you can subscribe to the weekly newsletter.

Every Friday, you’ll get a quick recap of all articles and tips posted on this site — entirely for free.

← Home