FocusManager Module

In most cases, the default focus behavior is sufficient for apps built with You.i React Native. The You.i React Native FocusManager module lets you override the default behavior. The following diagrams compare the default focus behavior with that of the FocusManager.

The following diagram explains the default focus behavior for a You.i React Native app using the buttons of a navigation pad.

Image

The following diagram explains the effects of using the FocusManager setNextFocus() method to override the default behavior.

Image

Methods

The following methods are available.

Method Name Description Parameter description
setNextFocus(fromRefOrTag, toRefOrTag, focusDirection) Sets the focus path between the two components with the given refs or tags in the mentioned direction.
Passing null as the to ref or tag on setNextFocus unsets the next focus in the given direction for the from element.
fromRefOrTag - The ref or node handle of the component from which the focus path originates.
toRefOrTag- The ref or node handle of the component at which the focus path ends.
focusDirection- The direction of the focus path. The valid directions are: up, down, right, left, forward, and reverse.
setFocusRoot(refOrTag, isFocusRoot) Controls whether the component with the given ref or tag is a focus root. refOrTag - The ref or a node handle of the component.
isFocusRoot - True if the component should be a focus root; false otherwise.
enableFocus(refOrTag) Enables the focusability of the component with the given tag.  refOrTag - The ref or a node handle of the component.
disableFocus(refOrTag) Disables the focusability of the component with the given tag. refOrTag - The ref or a node handle of the component.
setFocusable(refOrTag, focusable) Sets the focusability of the component with the given tag to the provided value. refOrTag -The ref or a node handle of the component.
focusable - The boolean value representing whether the component should be focusable or not.
focus(refOrTag) Requests that focus be moved to the component with the given tag. refOrTag - The ref or a node handle of the component.
blur(refOrTag) Requests that focus be removed from the component with the given tag. refOrTag - The ref or a node handle of the component.
clearNextFocus (fromRefOrTag) Unsets the next focus in all directions for the supplied ref or tag. fromRefOrTag - The ref or node handle of the component from which the focus path originates.

Usage

The following code snippet is an example of how to use setNextFocus() and setFocusRoot() to override the default focus behavior.

  componentDidMount() {
    FocusManager.setNextFocus(this.left, this.right, "left")
    FocusManager.setNextFocus(this.right, this.left, "right")
    FocusManager.setNextFocus(this.up, this.down, "up")
    FocusManager.setNextFocus(this.down, this.up, "down")
  }
  render() {
    const {isFocusRoot} = this.state
    return (
      <View
        style={{
          width:500,
          height:500
        }}
        ref={(ref) => this.root = ref}
      >
        <View>
          <Button
            title="^"
            ref={(ref) => this.up = ref}
          />
        </View>
        <View
          style={{
            flexDirection:'row',
            justifyContent: 'center',
            alignItems:'center'
          }}
        >
          <Button
            title="<"
            ref={(ref) => this.left = ref}
          />
          <Button
            title={isFocusRoot? "FOCUS ROOT: ON" : "FOCUS ROOT: OFF"}
            onPress={() => {
              FocusManager.setFocusRoot(this.root, !isFocusRoot)
              this.setState({isFocusRoot: !isFocusRoot})
            }}
          />
          <Button
            title=">"
            ref={(ref) => this.right = ref}
          />
        </View>
        <View>
          <Button
            title="v"
            ref={(ref) => this.down = ref}
          />
        </View>
      </View>
    )
  }