Focus Manager

The FocusManager module provides custom focus management functionality based on You.i TV's module.

It aims to provide a way for you to change the way focus transitions occur between components, as compared to the default behavior in React Native. APIs are imperative in nature as they help app developers separate business logic from layout logic.

Example usage

The following example is adapted from this You.i TV demo.

import { FocusManager } from "@amazon-devices/react-native-kepler";
import React, { useRef } from 'react';
import { findNodeHandle, StyleSheet, Text, TouchableOpacity, View } from 'react-native';

const FocusControl = () => {
    const touchableRef = useRef<TouchableOpacity>(null);

    return (
        <View style={styles.container}>
            <TouchableOpacity style={styles.button}
                              onPress={() => {
                                  console.log('[Youi.TV demo] focus source pressed');
                                  if (touchableRef?.current) {
                                      FocusManager.focus(findNodeHandle(touchableRef.current));
                                  }
                              }}
            ><Text style={styles.button_title}>{"Press Me"}</Text></TouchableOpacity>
            <TouchableOpacity
                ref={touchableRef}
                onPress={() => {
                    console.log('[Youi.TV demo] focus target pressed');
                }}
            ><Text style={styles.button_title}>{"I will gain focus"}</Text></TouchableOpacity>
        </View>
    );
}

const styles = StyleSheet.create({
    container: {
        flex: 1,
        flexDirection: 'column',
        justifyContent: 'center',
        alignItems: 'center',
    },
    button: {
        backgroundColor: '#33363b',
        borderRadius: 10,
        paddingHorizontal: 10,
        paddingVertical: 12,
    },
    button_title: {
        color: '#e6e6e6',
        fontFamily: 'Amazon-Ember-Regular',
        fontSize: 20
    },
});

export default FocusControl;

Methods

getFocused()

getFocused: () => number | undefined;

Retrieves the tag of the current focused component, returns undefined if nothing is in focus.

setNextFocus()

setNextFocus: (fromTag: ComponentOrHandleType, toTag: ComponentOrHandleType, direction: FocusDirection) => void;

Sets the next focus in the specified direction, from the component indicated by fromTag to the component indicated by toTag.

The list of possible directions is as follows:

export type FocusDirection =
    | 'up'
    | 'down'
    | 'left'
    | 'right'
    | 'all';

Type of tag arguments ComponentOrHandleType is the same for every method. It could be either:

• component's ref (e.g. from useRef)
  • however, due to type checking issues, this will cause transpiler issue, see known issues section
• component's id (e.g. value from findNodeHandle)

clearNextFocus()

clearNextFocus: (fromTag: ComponentOrHandleType, direction: FocusDirection = 'all') => void;

Clears every focus overrides, if any, created by setNextFocus starting from the component indicated by fromTag.

If direction parameter is not provided, it defaults to 'all' which clears focus for all directions.

setFocusRoot()

setFocusRoot: (tag: ComponentOrHandleType, isFocusRoot: boolean) => void;

Controls whether the component with the given ref or tag is a focus root, i.e. Sets whether focus can leave the component indicated by tag and its children.

• isFocusRoot - true if the component should be a focus root; false otherwise.

focus()

focus: (tag: ComponentOrHandleType) => void;

Brings the component indicated by tag into focus.

blur()

blur: (tag: ComponentOrHandleType) => void;

Removes the component indicated by tag from focus.

Known issues

• Calling these APIs from the useEffect hook can fail the first time that the component is mounted. This occurs due to a known issue in Vega where useEffect can execute earlier than expected. You can work around this issue by adding a timeout/delay to your useEffect logic.
• tag* parameters of the api accept either ref or the tag of the component. However, there is an issue with typechecking if a ref is used directly. Please use findNodeHandle as shown in example to resolve type related issues. You would get error similar to this one:
  • src/App.tsx:15:32 - error TS2345: Argument of type 'TouchableOpacity' is not assignable to parameter of type 'ComponentOrHandleType'.

See Also

• TVFocusGuideView

Last updated: May 19, 2026