react-navigation-header-buttons

This package will help you render buttons in the navigation bar and handle the styling, so you don't have to. It mimics the appearance of native navbar buttons and offers a simple but also flexible interface for you to interact with.

✅ DRY library api

✅ Works great with icons from @expo/vector-icons / react-native-vector-icons or any other icon library

✅ Supports Expo Router, and both JS and native stack

✅ Beautiful overflow menus for items that don't fit into the navbar

✅ Recipes and examples included

✅ Written in TS

✅ Test suite included (mostly good only for the maintainer, but hey, not bad to know it's there)

Demo App

Contains many examples in the example folder. I highly recommend you check it out to get a better idea of the api.

Quick Example

more screenshots

The corresponding code:

import * as React from 'react';
import MaterialIcons from '@expo/vector-icons/MaterialIcons';
import {
  HeaderButtons,
  Item,
  HiddenItem,
  OverflowMenu,
  Divider,
  ItemProps,
  HiddenItemProps,
  HeaderButtonProps,
  HeaderButton,
} from 'react-navigation-header-buttons';
import { Text } from 'react-native';

const MaterialHeaderButton = (props: HeaderButtonProps) => (
  // the `props` here come from 
  // you may access them and pass something else to `HeaderButton` if you like
  
);

const EditItem = ({ onPress }: Pick) => {
  return ;
};

const ReusableHiddenItem = ({ onPress }: Pick) => (
  
);

export function UsageWithIcons({ navigation }) {
  React.useLayoutEffect(() => {
    navigation.setOptions({
      title: 'Demo',
      headerRight: () => (
        
           alert('search')}
          />
           alert('Edit')} />
           (
              
            )}
          >
             alert('hidden1')} />
            
             alert('hidden2')} />
          
        
      ),
    });
  }, [navigation]);

  return ;
}

Installation & Setup

See Installation & Setup

Usage

HeaderButtons

Is a wrapper over all the visible header buttons (those can be text-buttons, icon-button, or any custom react elements).

You should provide the HeaderButtonComponent prop that encapsulates how all buttons rendered in children will look. Typically, you'll want to provide a component that wraps HeaderButton as seen in the example above. However, you're free to use your own component (see HeaderButton.tsx for reference).

In particular, it allows setting IconComponent, size and color in one place so that you don't need to repeat it for each icon-button - but you can override those for each Item if you like.

HeaderButtons accepts:

Item

Renders text, or icon inside a PlatformPressable. Take a look at the example above to see how to use it.

Item accepts:

Item also accepts other props that you'll typically not need to pass because HeaderButtonComponent already knows them (eg. iconSize) or because they are pulled from the React Navigation's theme object (color).

OverflowMenu

Defines the behavior for overflow button (if there is one). You can render OverflowMenu only by itself too, you do not need to wrap it in HeaderButtons. The most important prop is onPress which defines what kind of overflow menu we should show.

If OverflowMenu contains no valid child elements, nothing will be rendered at all. (No OverflowIcon, no wrapper.)

The package exports common handlers you can use, but you can provide your own too (via the onPress prop):

You can also use the react-native-menu to show the overflow menu, as seen in the example app.

OverflowMenu accepts:

> [!NOTE] > There are important limitations on what can be passed as children to OverflowMenu:

Children passed to OverflowMenu should be

• either HiddenItems
• or plain function components (no class components) without hooks that return HiddenItem, as seen in the example above.

Anything else will be ignored and will not appear in the overflow menus shown by overflowMenuPressHandlerActionSheet and overflowMenuPressHandlerPopupMenu. Only overflowMenuPressHandlerDropdownMenu supports rendering custom elements, such as `` (which is exported) or your custom ones.

This limitation may look weird, but it should not really bother you in any way: if you need to have state in your items, lift the state up. The limitation exists because we need to be able to transform declarative React elements into imperative calls (ActionSheetIOS.showActionSheetWithOptions / UIManager.showPopupMenu). If this is a problem for you for some reason, please raise an issue, and we'll see what can be done about it.

function MyComponent({ title }) {
  const [titleFromState, setTitle] = React.useState('from state hook');
  return (
     alert('fail')} />
  );
}

}
>
  
;

const HiddenItemWrapped = () =>  alert('hidden2')} />;
const HiddenItemWrappedTwice = ()=> 

}>
  
;

HiddenItem

HiddenItem accepts:

HeaderButtonsProvider / HeaderButtonsProviderPlain / HeaderButtonsProviderDropdownMenu

You need to wrap your root component with a HeaderButtons Provider. stackType is a required prop, which indicates whether you're using a native or JS stack.

Importing: import { your_chosen_provider } from 'react-navigation-header-buttons/your_chosen_provider'.

There are 3 providers to choose from. You'll get an actionable warning if you don't use the right one.

• HeaderButtonsProvider - the default, which assumes you will use overflowMenuPressHandlerDropdownMenu on Android but not iOS (because that's the default behavior that the library ships with).
• HeaderButtonsProviderPlain - use it if you're not planning to use overflowMenuPressHandlerDropdownMenu. It will shave a few kB off your bundle and Hermes won't have to parse the code that would not run in the end.
• HeaderButtonsProviderDropdownMenu - use it if you're planning to use overflowMenuPressHandlerDropdownMenu on all platforms.

Optional spaceAboveMenu prop can be used to set the distance between the top of the screen and the top of the overflow menu when using overflowMenuPressHandlerDropdownMenu.

HeaderButton

HeaderButton is where all the onPress, title and Icon-related props (color, size) meet to render actual button.

You can fully customize what it renders inside of the PlatformPressable using the renderButton?: (params: VisibleButtonProps) => ReactNode prop.

Recipes

Closing the overflow menu from overflowMenuPressHandlerDropdownMenu manually

overflowMenuPressHandlerDropdownMenu supports rendering custom items in the menu. In your item's onPress handler, you can call closeMenu to close the menu manually.

const { closeMenu } = useOverflowMenu();

Customizing the overflow menu

The default handler for overflow menu on iOS is overflowMenuPressHandlerActionSheet.

One of the usual things you may want to do is override the cancel button label on iOS - see example.

You can also use the react-native-menu (or similar) to show the overflow menu, as seen in the example app.

Using custom text transforms

Use the buttonStyle prop to set textTransform styles for button titles.

How to integrate in your project

This sections covers how you should use the library in your project. Please note that there are numerous example screens.

1 . Define one file where the styling of header buttons is taken care of.

// MyHeaderButtons.js

import * as React from 'react';
import MaterialIcons from 'react-native-vector-icons/MaterialIcons';
import { HeaderButtons, HeaderButton } from 'react-navigation-header-buttons';

// define IconComponent, color, sizes and OverflowIcon in one place
const MaterialHeaderButton = (props) => (
  
);

export const MaterialHeaderButtons = (props) => {
  return (
    
  );
};

2 . Import header buttons from the file defined previously.

// SomeScreen.js
import { MaterialHeaderButtons } from './MyHeaderButtons';
import { Item } from 'react-navigation-header-buttons';

React.useLayoutEffect(() => {
  navigation.setOptions({
    title: 'Demo',
    // use MaterialHeaderButtons with consistent styling across your app
    headerRight: () => (
      
         console.warn('add')}
        />
         console.warn('edit')} />
      
    ),
  });
}, [navigation]);

Theming

Colors for Android ripple effect, text and icons come from React Navigation's theme, so you do not need to work with colors, except in OverflowIcon. You can always override colors of text&icons (using color prop) or of the ripple effect on Android (using pressColor prop) as documented.

Known issues / TODOs

• styling support for material dropdown menu is missing
• item margins should be reviewed; don't hesitate to contribute - this could help
• RTL is not tested
• web support is experimental. On the web, you'll probably want to use different interaction patterns anyway.
• ripple may look different on the header buttons vs on the back button if your version of react navigation does not have this PR.