Apple TV Focus Engine: Step-by-Step Guide for Developers

As an Apple TV developer, I have a major challenge to work with Focus Engine. So basically, Focus engine is used to navigate or redirect your focus to one to another. The Focus Engine works seamlessly with Siri Remote actions such as up, down, left, and right. The main challenge, however, lies in navigating focus to non-directional objects. Any idea how it will work??

Don’t worry, in this blog I’ll be answering all your focus-related questions. Let’s dive in!

Before starting, If you are new to Apple TV development, be sure to check out my previous blog, Unlocking the World of Apple TV Development: Swift for Beginners, where I have explained all the basics you need to get started.

What is Focus Engine?

The Focus Engine is a built-in navigation system of Apple TV that decides which UI element is currently in focus and where focus should move next when the user interacts with the Siri Remote or another input device.

Focus Engine

Core Component of Focus Engine

Here are the following core components for Focus Engine –

UIFocusEnvironment – UIFocusEnvironment is a protocol used to create a bridge between the Focus Engine and UI components. Any UI components like (UIView, UIViewController, UIWindow, or UIFocusGuide) automatically conform to this protocol. Read More ……

UIFocusEnvironment

These are the following properties and methods are conform to UIFocusEnvironment –

• preferredFocusEnvironments – This property specifies which view should receive focus by default when the screen is displayed. You should return an array or list of views that need to focus.
  

  Code snipped: preferredFocusEnvironments

   

• setNeedsFocusUpdate() – This method requests the Focus Engine to update the focus. If it’s called for the first time or when no view is currently focused on the screen, it has no effect. However, if a specific view is already focused and you call this method again, the focus will reset according to the preferredFocusEnvironments. Therefore, use this method with caution.
  

  Code snipped: setNeedsFocusUpdate()

   

•  updateFocusIfNeeded() –This method is used to force an immediate update for all pending focus update requests. It should be called after setNeedsFocusUpdate().
  
  

  Code snipped: updateFocusIfNeeded()

   

• shouldUpdateFocus(in:) – Return a boolean value which helps the focus engine to determine whether the specific view is allowed focus update or not. By True means, focus will update. False means focus is blocked for a particular view. By Default, it is true.
  

  Code snipped: shouldUpdateFocus(in:)

   

• didUpdateFocus(in: with: ) –  This method is immediately called after the system update focus to the new view. This method has two parameters:-
  1. UIFocusUpdateContext – An instance of UIFocusUpdateContext containing metadata of the focus related update.
  2. UIFocusAnimationCoordinator – An instance of UIFocusAnimationCoordinator used for coordinating focus related animations.
  

  Code snipped: didUpdateFocus(in:with:)

   

UIFocusItem – An object that can be focused. UI components that conform to this protocol are eligible to receive focus. So there are some properties that are used for the focus engine :-

• canBecomeFocused – A boolean value is used to check specific item is eligible for focus or not.
• isFocused – A boolean value indicates whether the specific item is currently in focus or not.

UIFocusUpdateContext – This object provides specific information about a focus update from one view to another. It is mainly used to update the UI of both the newly focused view and the previously focused view according to the design. The following properties can be retrieved from this object –

• previouslyFocusedView –This object provides information about the view that was focused before the focus update. If there is no previous view found, so it will return nil.
• nextFocusedView – This object of the view that will be focused after the focus update. If there is no next view found, so it will return nil.
• previouslyFocusedItem – This item was focused before the focus update.
• nextFocusedItem – This item will be focus after focus update.
  

  Code snipped: UIFocusUpdateContext

   

UIFocusAnimationCoordinator – This object helps to apply animation on Focus updates. For example, scaling and colour change at the same time of focus switching is one of the animations that you can perform on focus update, and this is the default animation for Apple TV.

Code snipped: UIFocusAnimationCoordinator

UIFocusGuide – UIFocusGuide is a subclass of UILayoutGuide. It acts as an invisible helper for the Focus Engine, allowing focus to move between views that aren’t directly aligned. By default, Apple TV navigation only shifts focus to views that are positioned in the same direction. To overcome this limitation, UIFocusGuide was introduced.

When to use it? 

• Two buttons are separated by a big gap or another view that is not focusable.
• You want custom navigation between UI elements.

Let’s understand UIFocusGuide with demo.

I have created a demo application. It has two buttons, such as an “OK” button and a “Back” button. So I want to navigate my focus from one button to another. But these buttons are not in the same direction. Let’s start..

Demo: UIFocusGuide

Back Button to OK Button focus move with UIFocusGuide()

Step 1: Create object of UIFocusGuide

Code Snippet: Object of UIFocusGuide

Step 2: Create addFocusGuide() function and constraints for object of backButtonToOKButtonFocusGuide.

Code Snippet: UIFocusGuide()

The screenshot below demonstrates how UIFocusGuide works on your screen.

detailed view of UIFocusGuide

Followed these step for “OK”” Button to “Back” Button focus move with UIFocusGuide.

Check out my GitHub Link: https://github.com/shephaliTTN/Focus_engine

Conclusion

In tvOS, the Focus Engine defines how users interact with your app. Understanding focus environments, guides, and update contexts allows developers to control navigation beyond the default behaviour. Combined with coordinated animations, these capabilities ensure that Apple TV apps are both intuitive and visually engaging.

Happy coding!