/react-navigation

Skill: Header

Description

Use this when customizing the header in bottom tabs or drawer which render a JS-based header.

For native stack headers, use stacks.md instead.

When to Use

• Styling the built-in header in bottom tabs or drawer screens
• Adding header buttons, custom title content, or a custom background

Basic Example

The shared header options work the same in bottom tabs and drawer. The examples below use bottom tabs.

Static API

import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';

const AppTabs = createBottomTabNavigator({
  screens: {
    Home: {
      screen: HomeScreen,
      options: {
        title: 'Home',
        headerStyle: {
          backgroundColor: '#fff',
        },
        headerTintColor: '#111',
        headerRight: () => <HeaderAction />,
      },
    },
  },
});

Dynamic API

import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';

const Tab = createBottomTabNavigator();

function AppTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen
        name="Home"
        component={HomeScreen}
        options={{
          title: 'Home',
          headerStyle: {
            backgroundColor: '#fff',
          },
          headerTintColor: '#111',
          headerRight: () => <HeaderAction />,
        }}
      />
    </Tab.Navigator>
  );
}

• Use title, headerStyle, headerTintColor, headerTitleStyle, and headerTitleAlign for the default header. Put shared config in navigator screenOptions and per-screen overrides in options.
• Use headerShown: false for screens that contain a navigator - the header from the child navigator should be shown instead.

Common Features

Buttons and Custom Content

Use headerLeft, headerRight, headerTitle, and headerBackground when the default header layout is fine but specific pieces need customization.

Static API

import { Button, Text } from 'react-native';
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';

const AppTabs = createBottomTabNavigator({
  screens: {
    Inbox: {
      screen: InboxScreen,
      options: {
        headerLeft: ({ tintColor }) => (
          <Button title="Edit" color={tintColor} onPress={() => {}} />
        ),
        headerTitle: ({ tintColor, children }) => (
          <Text style={{ color: tintColor, fontSize: 18 }}>{children}</Text>
        ),
        headerRight: ({ tintColor }) => (
          <Button title="Done" color={tintColor} onPress={() => {}} />
        ),
      },
    },
  },
});

Dynamic API

import { Button, Text } from 'react-native';
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';

const Tab = createBottomTabNavigator();

function AppTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen
        name="Inbox"
        component={InboxScreen}
        options={{
          headerLeft: ({ tintColor }) => (
            <Button title="Edit" color={tintColor} onPress={() => {}} />
          ),
          headerTitle: ({ tintColor, children }) => (
            <Text style={{ color: tintColor, fontSize: 18 }}>{children}</Text>
          ),
          headerRight: ({ tintColor }) => (
            <Button title="Done" color={tintColor} onPress={() => {}} />
          ),
        }}
      />
    </Tab.Navigator>
  );
}

• headerLeft and headerRight receive props such as tintColor, pressColor, and pressOpacity.
• headerTitle is useful when the title needs custom typography, icons, or extra layout.
• Use headerTitleContainerStyle, headerLeftContainerStyle, and headerRightContainerStyle to customize the container styles.

Search Bar

Use headerSearchBarOptions to add a search button that expands into a search input in the header. If the search configuration depends on screen state, update it with navigation.setOptions(...).

Static API

import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';

const AppTabs = createBottomTabNavigator({
  screens: {
    Search: {
      screen: SearchScreen,
      options: {
        headerSearchBarOptions: {
          placeholder: 'Search',
          onChangeText: (text) => {
            // Do something
          },
        },
      },
    },
  },
});

Dynamic API

import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';

const Tab = createBottomTabNavigator();

function AppTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen
        name="Search"
        component={SearchScreen}
        options={{
          headerSearchBarOptions: {
            placeholder: 'Search',
            onChangeText: (text) => {
              // Do something
            },
          },
        }}
      />
    </Tab.Navigator>
  );
}

Translucent Headers

Use headerTransparent: true to let content show underneath the header. Combine it with headerBackground for effects such as a blur, gradient, or image background.

Static API

import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
import { BlurView } from 'expo-blur';
import { StyleSheet } from 'react-native';

const AppTabs = createBottomTabNavigator({
  screens: {
    Feed: {
      screen: FeedScreen,
      options: {
        headerTransparent: true,
        headerBackground: () => (
          <BlurView
            tint="light"
            intensity={100}
            style={StyleSheet.absoluteFill}
          />
        ),
      },
    },
  },
});

Dynamic API

import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
import { BlurView } from 'expo-blur';
import { StyleSheet } from 'react-native';

const Tab = createBottomTabNavigator();

function AppTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen
        name="Feed"
        component={FeedScreen}
        options={{
          headerTransparent: true,
          headerBackground: () => (
            <BlurView
              tint="light"
              intensity={100}
              style={StyleSheet.absoluteFill}
            />
          ),
        }}
      />
    </Tab.Navigator>
  );
}

• headerStyle does not apply when headerBackground is used. Style the element returned from headerBackground instead.
• Transparent headers overlap the content below. Add top spacing manually using useHeaderHeight hook from @react-navigation/elements

Canonical Docs

• Configuring the header bar
• Bottom Tabs Navigator
• Drawer Navigator

Related Skills

• bottom-tabs.md
• drawers.md
• stacks.md