Skip to main content
Version: 7.x

Elements Library

A component library containing the UI elements and helpers used in React Navigation. It can be useful if you're building your own navigator, or want to reuse a default functionality in your app.

Installation​

To use this package, ensure that you have @react-navigation/native and its dependencies (follow this guide), then install @react-navigation/elements:

npm install @react-navigation/elements

Components​

A component that can be used as a header. This is used by all the navigators by default.

Usage:

import { Header } from '@react-navigation/elements';

function MyHeader() {
  return <Header title="My app" />;
}
Try on Snack

To use the header in a navigator, you can use the header option in the screen options:

import { Header, getHeaderTitle } from '@react-navigation/elements';

const MyStack = createNativeStackNavigator({
  screenOptions: {
    header: ({ options, route, back }) => (
      <Header
        {...options}
        back={back}
        title={getHeaderTitle(options, route.name)}
      />
    ),
  },
  screens: {
    Home: HomeScreen,
  },
});
Try on Snack
note

This doesn't replicate the behavior of the header in stack and native stack navigators as the stack navigator also includes animations, and the native stack navigator header is provided by the native platform.

It accepts the following props:

headerTitle​

String or a function that returns a React Element to be used by the header. Defaults to scene title.

When a function is specified, it receives an object containing following properties:

  • allowFontScaling: Whether it scale to respect Text Size accessibility settings.
  • tintColor: Text color of the header title.
  • style: Style object for the Text component.
  • children: The title string (from title in options).
const RootStack = createNativeStackNavigator({
  screens: {
    Home: {
      screen: HomeScreen,
      options: {
        headerTitle: ({ allowFontScaling, tintColor, style, children }) => (
          <Text
            style={[style, { color: tintColor }]}
            allowFontScaling={allowFontScaling}
          >
            {children}
          </Text>
        ),
      },
    },
  },
});

headerTitleAlign​

How to align the header title. Possible values:

  • left
  • center

Defaults to center on iOS and left on Android.

headerTitleAllowFontScaling​

Whether header title font should scale to respect Text Size accessibility settings. Defaults to false.

headerLeft​

Function which returns a React Element to display on the left side of the header.

It receives an object containing following properties:

  • tintColor: The color of the icon and label.
  • pressColor: The color of the material ripple (Android >= 5.0 only).
  • pressOpacity: The opacity of the button when it's pressed (Android < 5.0, and iOS).
  • displayMode: How the element displays icon and title. Defaults to default on iOS and minimal on Android. Possible values:
    • default: Displays one of the following depending on the available space: previous screen's title, generic title (e.g. 'Back') or no title (only icon).
    • generic: Displays one of the following depending on the available space: generic title (e.g. 'Back') or no title (only icon). iOS >= 14 only, falls back to "default" on older iOS versions.
    • minimal: Always displays only the icon without a title.
  • href: The URL to open when the button is pressed on the Web.

You can use it to implement your custom left button, for example:

const RootStack = createNativeStackNavigator({
  screens: {
    Home: {
      screen: HomeScreen,
      options: {
        headerLeft: (props) => (
          <MyButton {...props} onPress={() => {
            // Do something
          }}>
        )
      }
    }
  }
})

headerRight​

Function which returns a React Element to display on the right side of the header.

It receives an object containing following properties:

  • tintColor: The color of the icon and label.
  • pressColor: The color of the material ripple (Android >= 5.0 only).
  • pressOpacity: The opacity of the button when it's pressed (Android < 5.0, and iOS).
const RootStack = createNativeStackNavigator({
  screens: {
    Home: {
      screen: HomeScreen,
      options: {
        headerLeft: (props) => (
          <MyButton {...props} onPress={() => {
            // Do something
          }}>
        )
      }
    }
  }
})

headerSearchBarOptions​

Options for the search bar in the header. When this is specified, the header will contain a button to show a search input.

It can contain the following properties:

  • ref: Ref to manipulate the search input imperatively. It contains the following methods:
    • focus - focuses the search bar
    • blur - removes focus from the search bar
    • setText - sets the search bar's content to given value
    • clearText - removes any text present in the search bar input field
    • cancelSearch - cancel the search and close the search bar
  • autoCapitalize: The auto-capitalization behavior. Possible values: none, words, sentences, characters.
  • autoFocus: Automatically focus search input on mount.
  • cancelButtonText: Text to be used instead of default Cancel button text (iOS only).
  • inputType: Type of the input. Possible values: text, phone, number, email.
  • onBlur: Callback that gets called when search input has lost focus.
  • onChangeText: Callback that gets called when the text changes.
  • onClose: Callback that gets called when search input is closed.
  • onFocus: Callback that gets called when search input has received focus.
  • placeholder: Text displayed when search input is empty.
React.useLayoutEffect(() => {
  navigation.setOptions({
    headerSearchBarOptions: {
      placeholder: 'Search',
      onChangeText: (text) => {
        // Do something
      },
    },
  });
}, [navigation]);

headerShadowVisible​

Whether to hide the elevation shadow (Android) or the bottom border (iOS) on the header.

This is a short-hand for the following styles:

{
  elevation: 0,
  shadowOpacity: 0,
  borderBottomWidth: 0,
}

If any of the above styles are specified in headerStyle along with headerShadowVisible: false, then the styles in headerStyle will take precedence.

headerStyle​

Style object for the header. You can specify a custom background color here, for example:

{
  backgroundColor: 'tomato',
}

Note that headerStyle won't take effect if you are also using headerBackground. In that case, you should style the element returned from headerBackground instead.

headerTitleStyle​

Style object for the title component

headerLeftContainerStyle​

Customize the style for the container of the headerLeft component, for example to add padding.

headerRightContainerStyle​

Customize the style for the container of the headerRight component, for example to add padding.

headerTitleContainerStyle​

Customize the style for the container of the headerTitle component, for example to add padding.

By default, headerTitleContainerStyle is with an absolute position style and offsets both left and right. This may lead to white space or overlap between headerLeft and headerTitle if a customized headerLeft is used. It can be solved by adjusting left and right style in headerTitleContainerStyle and marginHorizontal in headerTitleStyle.

headerBackgroundContainerStyle​

Style object for the container of the headerBackground element.

headerTintColor​

Tint color for the header

headerPressColor​

Color for material ripple (Android >= 5.0 only)

headerPressOpacity​

Press opacity for the buttons in header (Android < 5.0, and iOS)

headerTransparent​

Defaults to false. If true, the header will not have a background unless you explicitly provide it with headerBackground. The header will also float over the screen so that it overlaps the content underneath.

This is useful if you want to render a semi-transparent header or a blurred background.

Note that if you don't want your content to appear under the header, you need to manually add a top margin to your content. React Navigation won't do it automatically.

To get the height of the header, you can use HeaderHeightContext with React's Context API or useHeaderHeight.

headerBackground​

Function which returns a React Element to render as the background of the header. This is useful for using backgrounds such as an image or a gradient.

For example, you can use this with headerTransparent to render a blur view to create a translucent header.

const Stack = createStackNavigator({
  initialRouteName: 'Home',
  screens: {
    Home: {
      screen: HomeScreen,
      options: {
        headerTransparent: true,
        headerBackground: () => (
          <BlurView
            tint="dark"
            intensity={100}
            style={StyleSheet.absoluteFill}
          />
        ),
      },
    },
    Profile: ProfileScreen,
  },
});
Try on Snack

headerStatusBarHeight​

Extra padding to add at the top of header to account for translucent status bar. By default, it uses the top value from the safe area insets of the device. Pass 0 or a custom value to disable the default behavior, and customize the height.

HeaderBackground​

A component containing the styles used in the background of the header, such as the background color and shadow. It's the default for headerBackground. It accepts the same props as a View.

Usage:

<HeaderBackground style={{ backgroundColor: 'tomato' }} />

HeaderTitle​

A component used to show the title text in header. It's the default for headerTitle. It accepts the same props as a Text.

The color of title defaults to the theme text color. You can override it by passing a tintColor prop.

Usage:

<HeaderTitle>Hello</HeaderTitle>

HeaderButton​

A component used to show a button in header. It can be used for both left and right buttons. It accepts the following props:

  • onPress - Callback to call when the button is pressed.
  • href - The href to use for the anchor tag on web.
  • disabled - Boolean which controls whether the button is disabled.
  • accessibilityLabel - Accessibility label for the button for screen readers.
  • testID - ID to locate this button in tests.
  • tintColor - Tint color for the header button.
  • pressColor - Color for material ripple (Android >= 5.0 only).
  • pressOpacity - Opacity when the button is pressed if material ripple isn't supported by the platform.
  • style - Style object for the button.
  • children - Content to render for the button. Usually the icon.

Usage:

<HeaderButton
  accessibilityLabel="More options"
  onPress={() => console.log('button pressed')}
>
  <MaterialCommunityIcons
    name="dots-horizontal-circle-outline"
    size={24}
    color={tintColor}
  />
</HeaderButton>

HeaderBackButton​

A component used to show the back button header. It's the default for headerLeft in the stack navigator. It accepts the following props:

  • disabled - Boolean which controls Whether the button is disabled.
  • onPress - Callback to call when the button is pressed.
  • pressColor - Color for material ripple (Android >= 5.0 only).
  • backImage - Function which returns a React Element to display custom image in header's back button.
  • tintColor - Tint color for the header.
  • label - Label text for the button. Usually the title of the previous screen. By default, this is only shown on iOS.
  • truncatedLabel - Label text to show when there isn't enough space for the full label.
  • displayMode: How the back button displays icon and title. Defaults to default on iOS and minimal on Android. Possible values:
    • default: Displays one of the following depending on the available space: previous screen's title, generic title (e.g. 'Back') or no title (only icon).
    • generic: Displays one of the following depending on the available space: generic title (e.g. 'Back') or no title (only icon). iOS >= 14 only, falls back to "default" on older iOS versions.
    • minimal: Always displays only the icon without a title.
  • labelStyle - Style object for the label.
  • allowFontScaling - Whether label font should scale to respect Text Size accessibility settings.
  • onLabelLayout - Callback to trigger when the size of the label changes.
  • screenLayout - Layout of the screen.
  • titleLayout - Layout of the title element in the header.
  • canGoBack - Boolean to indicate whether it's possible to navigate back in stack.
  • accessibilityLabel - Accessibility label for the button for screen readers.
  • testID - ID to locate this button in tests.
  • style - Style object for the button.

Usage:

<HeaderBackButton label="Hello" onPress={() => console.log('back pressed')} />

MissingIcon​

A component that renders a missing icon symbol. It can be used as a fallback for icons to show that there's a missing icon. It accepts the following props:

  • color - Color of the icon.
  • size - Size of the icon.
  • style - Additional styles for the icon.

PlatformPressable​

A component which provides an abstraction on top of Pressable to handle platform differences. In addition to Pressable's props, it accepts following additional props:

  • pressColor - Color of material ripple on Android when it's pressed
  • pressOpacity - Opacity when it's pressed if material ripple isn't supported by the platform

Button​

A component that renders a button. In addition to PlatformPressable's props, it accepts following additional props:

  • variant - Variant of the button. Possible values are:
    • tinted (default)
    • plain
    • filled
  • color - Color of the button. Defaults to the theme's primary color.
  • children - Content to render inside the button.

In addition, the button integrates with React Navigation and accepts the same props as useLinkProps hook.

It can be used to navigate between screens by specifying a screen name and params:

<Button screen="Profile" params={{ userId: 'jane' }}>
  Go to Profile
</Button>

Or as a regular button:

<Button onPress={() => console.log('button pressed')}>Press me</Button>

Label​

The Label component is used to render small text. It is used in Bottom Tab Navigator to render the label for each tab.

In addition to the standard Text props, it accepts the following props:

  • tintColor - Color of the label. Defaults to the theme's text color.

Usage:

<Label>Home</Label>

ResourceSavingView​

A component which aids in improving performance for inactive screens by utilizing removeClippedSubviews. It accepts a visible prop to indicate whether a screen should be clipped.

Usage:

<ResourceSavingView visible={0}>{/* Content */}</ResourceSavingView>

Utilities​

SafeAreaProviderCompat​

A wrapper over the SafeAreaProvider component from `react-native-safe-area-context which includes initial values.

Usage:

<SafeAreaProviderCompat>{/* Your components */}</SafeAreaProviderCompat>

HeaderBackContext​

React context that can be used to get the back title of the parent screen.

import { HeaderBackContext } from '@react-navigation/elements';

// ...

<HeaderBackContext.Consumer>
  {(headerBack) => {
    if (headerBack) {
      const backTitle = headerBack.title;

      /* render something */
    }

    /* render something */
  }}
</HeaderBackContext.Consumer>;

HeaderShownContext​

React context that can be used to check if a header is visible in a parent screen.

import { HeaderShownContext } from '@react-navigation/elements';

// ...

<HeaderShownContext.Consumer>
  {(headerShown) => {
    /* render something */
  }}
</HeaderShownContext.Consumer>;

HeaderHeightContext​

React context that can be used to get the height of the nearest visible header in a parent screen.

import { HeaderHeightContext } from '@react-navigation/elements';

// ...

<HeaderHeightContext.Consumer>
  {(headerHeight) => {
    /* render something */
  }}
</HeaderHeightContext.Consumer>;

useHeaderHeight​

Hook that returns the height of the nearest visible header in the parent screen.

import { useHeaderHeight } from '@react-navigation/elements';

// ...

const headerHeight = useHeaderHeight();

getDefaultHeaderHeight​

Helper that returns the default header height. It takes the following parameters:

  • layout - Layout of the screen, i.e. an object containing height and width properties.
  • statusBarHeight - height of the statusbar

getHeaderTitle​

Helper that returns the title text to use in header. It takes the following parameters:

  • options - The options object of the screen.
  • fallback - Fallback title string if no title was found in options.