Skip to main content

Header

The Header component is a component that will appear at the top of your screen. It is used to hold navigation buttons and the screen title.

header-component

<Header
  titleTx="header:title"
  title="Header Title"
  leftIcon="back"
  rightIcon="bullet"
  onLeftPress={() => navigation.goBack()}
  onRightPress={() => Alert.alert("pressed")}
  style={{ height: 60 }}
  backgroundColor="purple"
  titleStyle={{ color: "white" }}
/>

Props​

titleMode​

The layout of the title relative to the action components.

center will force the title to always be centered relative to the header. If the title or the action buttons are too long, the title will be cut off. flex will attempt to center the title relative to the action buttons. If the action buttons are different widths, the title will be off-center relative to the header.

titleStyle​

The titleStyle prop is an optional prop that is used to set the style of the header title. This is a StyleProp<TextStyle> object.

<Header title="Header Title" titleStyle={{ color: "white" }} />

titleContainerStyle​

The titleContainerStyle prop is an optional prop that is used to set the style of the header title's outer container. This is a StyleProp<ViewStyle> object.

<Header title="Header Title" titleContainerStyle={{ backgroundColor: "purple" }} />

containerStyle​

The containerStyle prop is an optional prop that is used to set the style of the header's outer container. This is useful specifically on notched devices to override insets. This is a StyleProp<ViewStyle> object.

<Header title="Header Title" containerStyle={{ backgroundColor: "purple" }} />

style​

The style prop is an optional prop that is used to set the style of the header's inner container. You can use this to override the header's height. This is a StyleProp<ViewStyle> object.

<Header title="Header Title" style={{ height: 50 }} />

backgroundColor​

The backgroundColor prop is an optional prop that is used to set the background color of the header's outer container.

<Header title="Header Title" onLeftPress={() => navigation.goBack()} backgroundColor="purple" />

title​

The title is an optional prop that is used to set the header title. If this is not set, the titleTx prop must be present to set the title. If both are set, the title value will be used.

<Header title="Header Title" leftIcon="back" onLeftPress={() => navigation.goBack()} />

titleTx​

The titleTx is an optional prop that is used to lookup the translation for the header title. If this is not set, the title prop must be present to set the header title. If both are set, the title value will be used.

<Header titleTx="header:title" leftIcon="back" onLeftPress={() => navigation.goBack()} />

titleTxOptions​

The titleTxOptions is an optional prop that is used to pass props to the translation lookup for the header title. This is useful if you need to pass in dynamic values to the translation.

<Header
  titleTx="header:title"
  titleTxOptions={{ name: "John" }}
  leftIcon="back"
  onLeftPress={() => navigation.goBack()}
/>

leftIcon​

The leftIcon is an optional prop that is used to set the icon for the left navigation button. Options are 'back', 'bullet', and 'bug'. Custom icons can be created by using the Icon component. Once you create a custom icon, just pass the string name of the icon to the leftIcon prop.

<Header titleTx="header:title" leftIcon="back" onLeftPress={() => navigation.goBack()} />

leftIconColor​

The leftIconColor is an optional prop that is used to set the tint color of the left navigation icon.

<Header
  titleTx="header:title"
  leftIcon="back"
  leftIconColor="white"
  onLeftPress={() => navigation.goBack()}
/>

leftText​

The leftText is an optional prop that is used to set the text for the left navigation button. Overrides the leftIcon prop.

<Header titleTx="header:title" leftText="Back" onLeftPress={() => navigation.goBack()} />

leftTx​

The leftTx is an optional prop that is used to lookup the translation for the left navigation button. Overrides the leftIcon and leftText prop`.

<Header titleTx="header:title" leftTx="header:back" onLeftPress={() => navigation.goBack()} />

leftTxOptions​

The leftTxOptions is an optional prop that is used to pass props to the translation lookup for the left navigation button. This is useful if you need to pass in dynamic values to the translation.

<Header
  titleTx="header:title"
  leftTx="header:back"
  leftTxOptions={{ name: "John" }}
  onLeftPress={() => navigation.goBack()}
/>

LeftActionComponent​

The LeftActionComponent is an optional ReactElement prop that is used to set a custom component for the left navigation button. Overrides the leftIcon, leftText, leftTx, and onLeftText props (since the passed component is completely customizable).

<Header titleTx="header:title" LeftActionComponent={<Text>Back</Text>} />

onLeftPress​

The onLeftPress is an optional prop that is used to set the function to be called when the left navigation button is pressed.

<Header titleTx="header:title" leftIcon="back" onLeftPress={() => navigation.goBack()} />

rightIcon​

The rightIcon is an optional prop that is used to set the icon for the right navigation button. Custom icons can be created by using the Icon component. Once you create a custom icon, just pass the string name of the icon to the rightIcon prop.

<Header titleTx="header:title" rightIcon="back" onRightPress={() => navigation.goBack()} />

rightIconColor​

The rightIconColor is an optional prop that is used to set the tint color of the right navigation icon.

<Header
  titleTx="header:title"
  rightIcon="back"
  onRightPress={() => navigation.goBack()}
  rightIconColor="white"
/>

rightText​

The rightText is an optional prop that is used to set the text for the right navigation button. Overrides the rightIcon prop.

<Header titleTx="header:title" rightText="Back" onRightPress={() => navigation.goBack()} />

rightTx​

The rightTx is an optional prop that is used to lookup the translation for the right navigation button. Overrides the rightIcon and rightText prop`.

<Header titleTx="header:title" rightTx="header:back" onRightPress={() => navigation.goBack()} />

rightTxOptions​

The rightTxOptions is an optional prop that is used to pass props to the translation lookup for the right navigation button. This is useful if you need to pass in dynamic values to the translation.

<Header
  titleTx="header:title"
  rightTx="header:back"
  rightTxOptions={{ name: "John" }}
  onRightPress={() => navigation.goBack()}
/>

RightActionComponent​

The RightActionComponent is an optional ReactElement prop that is used to set a custom component for the right navigation button. Overrides the rightIcon, rightText, rightTx, and onRightPress props (since the right action component can customize all that).

<Header titleTx="header:title" RightActionComponent={<Text>Back</Text>} />

onRightPress​

The onRightPress is an optional prop that is used to set the function to be called when the right navigation button is pressed.

<Header titleTx="header:title" rightIcon="back" onRightPress={() => navigation.goBack()} />

safeAreaEdges​

The safeAreaEdges optional prop can be used to override the default safe area edges. By default, the header will use the top safe area edge. If you want to not account for the safe area edges, you can pass in [] to the safeAreaEdges prop.

<Header titleTx="header:title" safeAreaEdges={[]} />

Usage​

The Header is a flexible component that can be integrated within your application using a few different methods:

Method 1 (recommended) - Using navigation.setOptions() method in your screen component or useHeader() hook.​

This method gives you the most control over your Header and co-locates the logic inside of your screen while preserving react-navigation's optimizations by keeping it outside of the screen component's render lifecycle.

function AccountScreen(props) {
  const { navigation } = props

  useLayoutEffect(() => {
    navigation.setOptions({
      headerShown: true,
      header: () => <Header title="Hello" />,
    })
  }, [])

  return <Screen />
}

A convenience useHeader hook is provided that abstracts and cleans up some of this logic.

function AccountScreen(props) {
  useHeader({
    title: "Hello",
  })

  return <Screen />
}

Method 2 - Directly in the render of you screen component.​

The Header can be rendered directly in your screen's body. This gives you the most control over the Header component at the expense of performance as it is now a part of the screen's render lifecycle.

function AccountScreen(props) {
  return (
    <View>
      <Header title="Hello" />
    </View>
  )
}

If you prefer this method, it might be a good idea to memoize the component to prevent unnecessary re-renders.

Method 3 - Defining the header in your navigator/screen config.​

If your Header shares a lot of the same logic within a navigator, it might be a better solution to set the Header inside the navigator config or navigator's screen config. For any customization between screens, you will still need to set the Header props using navigation.setOptions(). Additionally, the Header might need to be updated/refactored to use react-navigation's header properties as it isn't very compatible out-of-the-box.

<Stack.Navigator
  screenOptions={{
    header: (props) => <Header title={props.options.headerTitle ?? props.route.name} />,
  }}
/>

Or, you can define it on the screen config.

<Stack.Navigator screenOptions={{ headerShown: false }}>
  <Stack.Screen
    name="Welcome"
    component={WelcomeScreen}
    options={{ headerShown: true, header: () => <Header title="Hello" /> }}
  />
</Stack.Navigator>