@equinor/mad-navigation v0.3.0

Mad Navigation

Mad Navigation is a layer on top of React Navigation that provides additional features to provide a better experience for developers.

Features

• Display custom sub-headers automatically on screens.
• Add onRouteChange prop to navigation containers
• (more features coming soon)

Tested on and confirmed working with these versions

Note: This package will most likely work well with any version of React Navigation v6. If you are running a newer version of v6 and some features are missing, create an issue here

Installation

npm install @react-navigation/native @equinor/mad-navigation

You also have to install the navigators you want to use, e.g @react-navigation/bottom-tabs and @react-navigation/native-stack

Usage

If you want to add custom sub-headers to your navigation system, you first have to create custom navigator-creator functions. You can do so with createBottomTabNavigatorFactory and createNativeStackNavigatorFactory.

Step 1: Create your custom sub-header:

import { Text } from "react-native";
export const CustomSubHeader = () => <Text>This is a custom sub-header</Text>;

Step 2: Create your new navigator-creator functions:

import {
    createBottomTabNavigatorFactory,
    createNativeStackNavigatorFactory,
} from "@equinor/mad-navigation";
import { CustomSubHeader } from "path/to/subHeader";

export const createBottomTabNavigator = createBottomTabNavigatorFactory(CustomSubHeader);
export const createNativeStackNavigator = createNativeStackNavigatorFactory(CustomSubHeader);

Follow React Navigation’s documentation. When you get to the point where you are creating a navigator, import your custom navigator-creators.

You can also import NavigationContainer from this package if you need a onRouteChange prop.

For example:

//import { createNativeStackNavigator } from '@react-navigation/native-stack';
//replace the above line with the line below
import { createNativeStackNavigator } from "path/to/createNativeStackNavigator";

Once you've finished the steps above, you should see your custom sub-header in your application. By default, the sub-header will display if navigator’s header is displayed. if you want to overwrite this behaviour, use the custom customSubHeaderShown option. This option can be applied in the Screen’s options prop, or in the Group or Navigator's screenOptions prop. You can also use customSubHeaderFloat if you want the sub header to float above the content instead of pushing the screen's content down.

<Stack.Navigator
    screenOptions={{
        // add it here
        customSubHeaderShown: false,
        customSubHeaderFloat: false,
    }}
>
    <Stack.Group
        screenOptions={{
            // or here
            customSubHeaderShown: true,
            customSubHeaderFloat: true,
        }}
    >
        <Stack.Screen
            name="Discover"
            component={DiscoverScreen}
            options={{
                // or here
                customSubHeaderShown: false,
                customSubHeaderFloat: false,
            }}
        />
    </Stack.Group>
</Stack.Navigator>

CAUTION: sub-headers will not work properly if headerLargeTitle is set to true, and headerLargeTitle make it hard for elements in your application to calculate header height. It is therefore not recommended to use headerLargeTitle. If you still decide to use it, we recommend disabling sub-headers where it is used, as the sub-headers may cause the header to not work as expected.

<DiscoverStack.Navigator
    initialRouteName="Discover"
    screenOptions={{
        headerLargeTitle: true,
        headerLargeTitleShadowVisible: true,
        headerLargeTitleStyle: { fontFamily: "Equinor-Bold" },
        headerTitleStyle: {
            fontFamily: "Equinor-Regular",
        },
        headerBackTitleStyle: { fontFamily: "Equinor-Regular" },
        customSubHeaderShown: false,
    }}
>

Development

This package has custom navigators created by following this guide. If you want to add additional navigators or update the current navigators to be in sync with React Navigation’s navigators, follow these steps:

1. Go to React Navigation’s repository and find the navigator you want to copy (usually located within package-name/src/navigators directory). Copy the source code.
2. paste the source code into this package and update imports. Imports that are not provided by the react navigation package should be created manually (usually only the XNavigationConfig). The props can also be recreated by exported types from react navigation + your copied XNavigationConfig.
3. Modify the descriptors using the createMadDecorators function.
4. Use the modified descriptors instead of the original descriptors in the return function