react-native-navigation/docs/docs/topBar-buttons.md

Button options

The following options can be used to customise buttons.

{
  id: 'buttonOne',
  icon: require('icon.png'),
  component: {
    name: 'example.CustomButtonComponent'
  },
  text: 'Button one',
  enabled: true,
  disableIconTint: false,
  color: 'red',
  disabledColor: 'black',
  testID: 'buttonOneTestID',
  fontFamily: 'Helvetica',
  fontSize: 10
  fontWeight: 'regular', // Available on iOS only, will ignore fontFamily style and use the iOS system fonts instead. Supported weights are: 'regular', 'bold', 'thin', 'ultraLight', 'light', 'medium', 'semibold', 'heavy' and 'black'.
  // Android only
  showAsAction: 'ifRoom', // See below for details.
  // iOS only
  systemItem: 'done', // Sets a system bar button item as the icon. Matches UIBarButtonSystemItem naming. See below for details.
}

iOS System Items

On iOS, UIKit supplies some common bar button glyphs for developers to use. The following values can be supplied as values to to systemItem to use them as an icon for your button.

• done
• cancel
• edit
• save
• add
• flexibleSpace
• fixedSpace
• compose
• reply
• action
• organize
• bookmarks
• search
• refresh
• stop
• camera
• trash
• play
• pause
• rewind
• fastForward
• undo
• redo

More information about these glyphs can be found in Apple’s Human Interface Guidelines.

Android showAsAction

The keyword showAsAction configures when and how an item should appear as an action item in the app bar. A menu item can appear as an action item only when the activity includes an app bar.

• always
• ifRoom
• never
• withText

More info about showAsAction values

Declaring Buttons statically

Buttons can be defined in a screen’s options:

class MyScreen extends Component {
  static options(passProps) {
    return {
      topBar: {
        leftButtons: [
          {
            id: 'buttonOne',
            icon: require('icon.png')
          }
        ],
        rightButtons: [],
      }
    };
  }
  
}

Declaring buttons dynamically

TopBar buttons can be declared dynamically as well when adding a screen to the layout hierarchy.

Navigation.push(this.props.componentId, {
  component: {
    name: 'navigation.playground.PushedScreen',
    options: {
      topBar: {
        rightButtons: [
          {
            id: 'buttonOne',
            icon: require('icon.png')
          }
        ]
      }
    }
  }
}

Handling button press events

Navigation sends events on button clicks, to which you can subscribe from anywhere using Navigation.events().registerNavigationButtonPressedListener((event) => {}). Additionally the component can listen to the button clicks just for its own buttons (via componentId) by using events().bindComponent(this). This has to be called if you want the component to handle navigation events, such as navigationButtonPressed. Example:

class MyScreen extends Component {
  static options(passProps) {
    return {
      topBar: {
        rightButtons: {
          id: 'buttonOne',
          icon: require('icon.png')
        }
      }
    };
  }

  constructor(props) {
    super(props);
    Navigation.events().bindComponent(this); // <== Will be automatically unregistered when unmounted
  }

  navigationButtonPressed({ buttonId }) {
    // will be called when "buttonOne" is clicked
  }
}

Modifying buttons at runtime

As buttons are part of a screen’s options, they can be modified like any other styling option using the mergeOptions command.

Setting buttons

The following command will set the screen’s right buttons. If the screen already has Right Buttons declared - they will be overridden.

Navigation.mergeOptions(this.props.componentId, {
  topBar: {
    rightButtons: [
      {
        id: 'myDynamicButton',
        text: 'My Button'
      }
    ]
  }
});

Removing buttons

Buttons can be removed by setting zero buttons, as shown in the snippet below.

Navigation.mergeOptions(this.props.componentId, {
  topBar: {
    rightButtons: []
  }
});