Focus Management

​

Focus management overview video

​

Basic focus handling in Vega

​

How to indicate focus

​

Component with out-of-the-box indications when focused

Component	Not in focus (default state)	Focused (opacity changed)

​

Responding to focus In Vega

const FocusablePressable = () => {
  const [isFocused, setIsFocused] = useState(false);  // Using state to track focus.

  return (
    <Pressable
      style={[styles.button, isFocused && styles.buttonFocused]}  // Conditionally providing the style based on focus state.
      onFocus={() => setIsFocused(true)} // Setting focus state via onFocus().
      onBlur={() => setIsFocused(false)} // Unsetting focus state with onBlur().
    >
      <Text style={[styles.text]}>
        {'Presssable'}
      </Text>
    </Pressable>
  );
};

const styles = StyleSheet.create({
  button: {
    padding: 10,
    backgroundColor: 'gray',  // Providing a default border color.
    borderRadius: 5,
  },
  buttonFocused: {
    borderWidth: 2,
    borderColor: 'blue', // Changing the border color to blue when in focus.

  },
});

​

Components focusability in Vega

​

Component Focusability Demo

​

Demo screen capture - component

• When the component receives focus, it is rendered with an orange border.
• The focusable={} button is used to toggle the value between true/false and undefined (prop is not provided).
• The pointerEvents={} button is used to toggle the value between auto, none, and box-none.
• The counters for onFocus() and onBlur() are used to check whether the corresponding callback has been executed. The counter could be reset with the Reset Counts button.

​

Container Focusability Demo

​

Demo screen capture - container

• When component/container receives focus, it is rendered with an orange border.
• The focusable={} button is used to toggle the value for the focusable prop between true/false and undefined.
• The Show children button is used to populate or remove the children inside the container.
• The counters for onFocus and onBlur are used to check whether the corresponding callback has been executed. The counter could be reset with the Reset Counts button.

​

Focus Navigation Behaviors in Vega

​

Cartesian focus management

• Pressing the Down button moves focus to the item directly below.
• Pressing the Right button moves focus to the adjacent item horizontally.

​

Case studies for Cartesian focus navigation algorithm in different layouts

​

Case Study 1: Investigating cases where pressing the DOWN button is not resulting in the focus moving to the item directly below

[  Top Item ] [Top Item side]
      |
      v
            [Side Item]
[Bottom Item]

• When pressing the DOWN button from [Top Item]: Focus moves to [Small Item].
• This occurs because the bottom edge of the [Small Item] and the top edge of the [Bottom Item] don’t overlap horizontally.

• With similar component positioning, the focus moves to [Bottom Item] instead.
• This different behavior occurs because the bottom edge of the [Small Item] now overlaps horizontally with the top edge of the [Bottom Item].

• When pressing the DOWN button from [Top Item]:
  • Focus moves to [Small Item].
• This occurs because the left edge of the [Small Item] overlaps vertically with the right edge of the [Top Item].

• With similar component positioning: Focus moves to [Bottom Item] instead.
• This occurs because the left edge of the [Small Item] does not overlaps vertically with the right edge of the [Top Item].

• Edge overlap between components matters.
• Distance to next focusable element is considered.
• Component positioning critically affects navigation paths.

• FocusManager.setNextFocus() method.
• nextFocusUp/nextFocusDown/nextFocusLeft/nextFocusRight props.
• FocusManager.focus() to programmatically assign focus to a specific element.
• destination prop from <TVFocusGuideView> control the focus when navigating into a container.

​

Case Study 2: Focus skipping the full-width element when navigating between rows of items with different widths

[ Item 1 ]
[      Full-width item         ]
[ Item 3 ] [ Item 4 ] [ Item 5 ]

• Forcing focus moves from [Item 1] to [Full-width item] upon pressing the DOWN button.
• Up navigation from [Item 3] to [Full-width item].
• Down navigation from [Full-width item] to [Item 3].

​

Focus Behavior in Vega

​

Handling focus between an item across different rows

​

Restore focus

• @amazon-devices/react-navigation__stack
  • ❌ No automatic focus restoration
• @amazon-devices/react-navigation__native-stack
  • ❌ No automatic focus restoration

​

Implementation options for restoring focus

• Store a reference to the most recently focused element for each screen.
• Use useFocusEffect() to detect when a user returns to a screen.
• Inside useFocusEffect(), call FocusManager.setFocus() with the stored reference to restore focus to the correct element.

​

Configure initial focus

• The hasTVPreferredFocus prop sets focus during the component initial mount. This prop only works during the initial rendering phase.
• You can combine useEffect or useFocusEffect (From React Navigation) with FocusManager.setFocus() for a more dynamic approach, particularly when your app needs to actively restore focus states within a multi-page application built with React Navigation. This approach provides more flexibility and control over focus behavior beyond the initial mount phase.

​

Customize focus behavior

• Focus Props and Methods: If you want to override the default focus behavior for specific components in your app, Vega supports various focus-related props and TurboModule methods. Think of these as defining edge cases where you don’t want the default behavior.
• Specialized Focus Components: In some cases, you might want behavior that differs in some systematic way from the default Cartesian behavior (for example, you might be familiar with TVFocusGuideView). This section contains a list of custom components (including TVFocusGuideView) supported by Vega.

​

Focus props and methods

• nextFocusUp
• nextFocusDown
• nextFocusLeft
• nextFocusRight

• Setting the value to undefined re-enables default Cartesian behavior for a button press in the given direction.
• If you want a more imperative API, the FocusManager TurboModule provides functions that mirror the behavior of the focus props. There’s also a setFocusRoot API that prevents focus from leaving a component or its children. See Focus Manager (Vega) for more details.

const useNodeHandle = (ref) => {
  const [nodeHandle, setNodeHandle] = React.useState<number | null>(null);
  React.useEffect(() => {
    if (ref.current) {
      setNodeHandle(findNodeHandle(ref.current));
    }
  }, [ref.current]);
  return nodeHandle;
};

const focusableComponent = () => {
  const ref1 = React.useRef(null);
  const ref2 = React.useRef(null);
  const ref3 = React.useRef(null);

  const ref1Handle = useNodeHandle(ref1);
  const ref2Handle = useNodeHandle(ref2);
  const ref3Handle = useNodeHandle(ref3);

  // Three focusable components explicitly define some or all of their
  // directional overrides. Overrides that sets the next focus to the same
  // component effectively act to block the button press. For components
  // that have directions that are not explicitly declared or set to undefined,
  // the fallback behavior of Cartesian focus strategy will be taken.
  return (
          <View>
            <TouchableOpacity
                    ref={ref1}
                    onPress={() => {}}
                    // block 'up' presses
                    nextFocusUp={ref1Handle || undefined}
                    // block 'right' presses
                    nextFocusRight={ref1Handle || undefined}
                    // explicitly focus on Component 2 on 'left' press
                    nextFocusLeft={ref2Handle || undefined}
                    // explicitly focus on Component 3 on 'down' press
                    nextFocusDown={ref3Handle || undefined}>Component 1</TouchableOpacity>
            <TouchableOpacity
                    ref={ref2}
                    onPress={() => {}}
                    // explicitly focus on Component 1 on 'right' press
                    nextFocusRight={ref1Handle || undefined}>Component 2</TouchableOpacity>
            <TouchableOpacity
                    ref={ref3}
                    onPress={() => {}}
                    // explicitly focus on Component 1 on 'up' press
                    nextFocusUp={ref1Handle || undefined}>Component 3</TouchableOpacity>
          </View>
  );
};

​

FocusManager turbo module

• setNextFocus()—
• clearNextFocus()—
• setFocusRoot()
• focus()—
• blur()
• getFocused()

​

Specialized focus components

​

TVFocusGuideView

​

Dispatching synchronous focus events

• When an app updates the zIndex on an item upon receiving focus, the change of zIndex causes the item to be removed and reinserted. As a result, the item is no longer focused and focus is lost. In another case, if the item was placed inside a <TVFocusGuideView>, instead of loosing the focus, TVFocusGuide recovers the focus onto the first child.

​

Should your app enable synchronous focus

• You are seeing issues where focus is being reset back to the first item inside a <TVFocusGuideView/>.
• There is a specific UI requirement that strictly enforces all the side effects of focusing or blurring an item that has completed before focus moves to another item.

• Keep the usage as minimal as possible.
• Your app needs to be optimized and follow the App Performance Best Practices to avoid unnecessary re-rendering.
• Keep the onFocus() and onBlur() as light weight as possible to avoid blocking the UI thread longer than needed.

​

Known impacts and solutions

​

Longer animations might be skipped during rapid key presses

​

Laggy behavior observed in the app when there are unnecessary re-renders

​

Frame drops might be observed with in-progress animation when a focus or blur event is dispatched

​

How to enable the synchronous focus event

1. When enableSynchronousFocusEventsVega is set to true. The app shouldn’t call any methods that could programmatically alter focus inside the onFocus() and onBlur() implementations. These methods include:
   • requestTVFocus()
   • FocusManager.Focus() and .Blur()
   • ref.focus() and ref.blur()
2. Don’t change the value of enableSynchronousFocusEventsVega after the initial render.
3. Don’t mix components with different enableSynchronousFocusEventsVega values under a common parent container. For example, avoid the following pattern that mixes the usage of enableSynchronousFocusEventsVega for a component:
   <View>
     <Pressable enableSynchronousFocusEventsVega>
     <Pressable >
     <Pressable enableSynchronousFocusEventsVega>
   <View>
   
   Instead, use a pattern in which all components in a container have the same value:
   <PageContainer>
     <Navbar>
       <TouchableOpacity enableSynchronousFocusEventsVega>
       <TouchableOpacity enableSynchronousFocusEventsVega>
     </Navbar>
     <HomeContent>
       <Pressable >
       <Pressable >
     </HomeContent>
   </PageContainer>
   
   Sample Usage:
   <View
      focusable
      enableSynchronousFocusEventsVega
      onFocus={() => { console.log('view-onfocus'); }}
      onBlur={()=> { console.log('view-onBlur');}}
   >
      <Text>
          {`Sample For making a View that received onBlur/onFocus synchronous`}
      </Text>
   </View>
   
   <TouchableOpacity
      enableSynchronousFocusEventsVega
      onPress={() => { console.log("touchableOpacity-pressed"); }}
      onFocus={() => { console.log('touchableOpacity-onfocus'); }}
      onBlur={()=> { console.log('touchableOpacity-onBlur'); }}
   >
      <Text>
          {`Sample For making a TouchableOpacity that received onBlur/onFocus synchronous`}
      </Text>
   </TouchableOpacity>
   

​

react-native, react-native-tvos, and react-native-kepler

​

Related topics

• Vega TV Interfaces Sample App