Skip to content

Commit be2a278

Browse files
lukewalczaklukewalczak
authored
docs: adjust guide for using createMaterialBottomTabNavigator (#4037)
1 parent 6b11c68 commit be2a278

File tree

4 files changed

+246
-91
lines changed

4 files changed

+246
-91
lines changed

‎docs/docs/guides/09-bottom-navigation.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
title: Using BottomNavigation with React Navigation
3+
---
4+
5+
A material-design themed tab bar on the bottom of the screen that lets you switch between different routes with animation. Routes are lazily initialized - their screen components are not mounted until they are first focused.
6+
7+
This wraps the [`BottomNavigation`](https://callstack.github.io/react-native-paper/docs/components/BottomNavigation/) component from `react-native-paper`, however if you [configure the Babel plugin](https://callstack.github.io/react-native-paper/docs/guides/getting-started/), it won't include the whole library in your bundle.
8+
9+
<img src="/react-native-paper/screenshots/material-bottom-tabs.gif" style={{ width: '420px', maxWidth: '100%', margin: '16px 0' }} />
10+
11+
:::info
12+
To use this navigator, ensure that you have [`@react-navigation/native` and its dependencies (follow this guide)](https://reactnavigation.org/docs/getting-started):
13+
:::
14+
15+
> For a complete example please visit `createMaterialBottomTabNavigator` [snack](https://snack.expo.dev/@react-native-paper/creatematerialbottomtabnavigator)
16+
17+
## API Definition
18+
19+
To use this tab navigator, import it from `react-native-paper/react-navigation`:
20+
21+
```js
22+
import { createMaterialBottomTabNavigator } from 'react-native-paper/react-navigation';
23+
24+
const Tab = createMaterialBottomTabNavigator();
25+
26+
function MyTabs() {
27+
return (
28+
<Tab.Navigator>
29+
<Tab.Screen name="Home" component={HomeScreen} />
30+
<Tab.Screen name="Settings" component={SettingsScreen} />
31+
</Tab.Navigator>
32+
);
33+
}
34+
```
35+
36+
> For a complete usage guide please visit [Tab Navigation](https://reactnavigation.org/docs/tab-based-navigation/)
37+
38+
### Props
39+
40+
The `Tab.Navigator` component accepts following props:
41+
42+
#### `id`
43+
44+
Optional unique ID for the navigator. This can be used with [`navigation.getParent`](https://reactnavigation.org/docs/navigation-prop#getparent) to refer to this navigator in a child navigator.
45+
46+
#### `initialRouteName`
47+
48+
The name of the route to render on first load of the navigator.
49+
50+
#### `screenOptions`
51+
52+
Default options to use for the screens in the navigator.
53+
54+
#### `backBehavior`
55+
56+
This controls what happens when `goBack` is called in the navigator. This includes pressing the device's back button or back gesture on Android.
57+
58+
It supports the following values:
59+
60+
- `firstRoute` - return to the first screen defined in the navigator (default)
61+
- `initialRoute` - return to initial screen passed in `initialRouteName` prop, if not passed, defaults to the first screen
62+
- `order` - return to screen defined before the focused screen
63+
- `history` - return to last visited screen in the navigator; if the same screen is visited multiple times, the older entries are dropped from the history
64+
- `none` - do not handle back button
65+
66+
#### `shifting`
67+
68+
Whether the shifting style is used, the active tab icon shifts up to show the label and the inactive tabs won't have a label.
69+
70+
By default, this is `true` when you have more than 3 tabs. Pass `shifting={false}` to explicitly disable this animation, or `shifting={true}` to always use this animation.
71+
72+
#### `labeled`
73+
74+
Whether to show labels in tabs. When `false`, only icons will be displayed.
75+
76+
#### `activeColor`
77+
78+
Custom color for icon and label in the active tab.
79+
80+
#### `inactiveColor`
81+
82+
Custom color for icon and label in the inactive tab.
83+
84+
#### `barStyle`
85+
86+
Style for the bottom navigation bar. You can pass custom background color here:
87+
88+
```js
89+
<Tab.Navigator
90+
initialRouteName="Home"
91+
activeColor="#f0edf6"
92+
inactiveColor="#3e2465"
93+
barStyle={{ backgroundColor: '#694fad' }}
94+
>
95+
{/* ... */}
96+
</Tab.Navigator>
97+
```
98+
99+
If you have a translucent navigation bar on Android, you can also set a bottom padding here:
100+
101+
```js
102+
<Tab.Navigator
103+
initialRouteName="Home"
104+
activeColor="#f0edf6"
105+
inactiveColor="#3e2465"
106+
barStyle={{ paddingBottom: 48 }}
107+
>
108+
{/* ... */}
109+
</Tab.Navigator>
110+
```
111+
112+
#### `theme`
113+
114+
Enables the customization of default theme attributes (e.g. colors) or facilitates the utilization of a personalized custom theme.
115+
116+
### Options
117+
118+
The following [options](https://reactnavigation.org/docs/screen-options) can be used to configure the screens in the navigator:
119+
120+
#### `title`
121+
122+
Generic title that can be used as a fallback for `headerTitle` and `tabBarLabel`.
123+
124+
#### `tabBarIcon`
125+
126+
Function that given `{ focused: boolean, color: string }` returns a React.Node, to display in the tab bar.
127+
128+
#### `tabBarColor`
129+
130+
Color for the tab bar when the tab corresponding to the screen is active. Used for the ripple effect. This is only supported when `shifting` is `true`.
131+
132+
#### `tabBarLabel`
133+
134+
Title string of a tab displayed in the tab bar. When undefined, scene `title` is used. To hide, see `labeled` option in the previous section.
135+
136+
#### `tabBarBadge`
137+
138+
Badge to show on the tab icon, can be `true` to show a dot, `string` or `number` to show text.
139+
140+
#### `tabBarAccessibilityLabel`
141+
142+
Accessibility label for the tab button. This is read by the screen reader when the user taps the tab. It's recommended to set this if you don't have a label for the tab.
143+
144+
#### `tabBarTestID`
145+
146+
ID to locate this tab button in tests.
147+
148+
### Events
149+
150+
The navigator can [emit events](https://reactnavigation.org/docs/navigation-events) on certain actions. Supported events are:
151+
152+
#### `tabPress`
153+
154+
This event is fired when the user presses the tab button for the current screen in the tab bar. By default a tab press does several things:
155+
156+
- If the tab is not focused, tab press will focus that tab
157+
- If the tab is already focused:
158+
- If the screen for the tab renders a scroll view, you can use [`useScrollToTop`](https://reactnavigation.org/docs/use-scroll-to-top) to scroll it to top
159+
- If the screen for the tab renders a stack navigator, a `popToTop` action is performed on the stack
160+
161+
To prevent the default behavior, you can call `event.preventDefault`:
162+
163+
```js
164+
React.useEffect(() => {
165+
const unsubscribe = navigation.addListener('tabPress', (e) => {
166+
// Prevent default behavior
167+
168+
e.preventDefault();
169+
// Do something manually
170+
// ...
171+
});
172+
173+
return unsubscribe;
174+
}, [navigation]);
175+
```
176+
177+
### Helpers
178+
179+
The tab navigator adds the following methods to the navigation prop:
180+
181+
#### `jumpTo`
182+
183+
Navigates to an existing screen in the tab navigator. The method accepts following arguments:
184+
185+
- `name` - _string_ - Name of the route to jump to.
186+
- `params` - _object_ - Screen params to pass to the destination route.
187+
188+
<samp id="material-tab-jump-to" />
189+
190+
```js
191+
navigation.jumpTo('Profile', { name: 'Michaś' });
192+
```
193+
194+
## Example
195+
196+
```js
197+
import { createMaterialBottomTabNavigator } from 'react-native-paper/react-navigation';
198+
import MaterialCommunityIcons from 'react-native-vector-icons/MaterialCommunityIcons';
199+
200+
const Tab = createMaterialBottomTabNavigator();
201+
202+
function MyTabs() {
203+
return (
204+
<Tab.Navigator
205+
initialRouteName="Feed"
206+
activeColor="#e91e63"
207+
barStyle={{ backgroundColor: 'tomato' }}
208+
>
209+
<Tab.Screen
210+
name="Feed"
211+
component={Feed}
212+
options={{
213+
tabBarLabel: 'Home',
214+
tabBarIcon: ({ color }) => (
215+
<MaterialCommunityIcons name="home" color={color} size={26} />
216+
),
217+
}}
218+
/>
219+
<Tab.Screen
220+
name="Notifications"
221+
component={Notifications}
222+
options={{
223+
tabBarLabel: 'Updates',
224+
tabBarIcon: ({ color }) => (
225+
<MaterialCommunityIcons name="bell" color={color} size={26} />
226+
),
227+
}}
228+
/>
229+
<Tab.Screen
230+
name="Profile"
231+
component={Profile}
232+
options={{
233+
tabBarLabel: 'Profile',
234+
tabBarIcon: ({ color }) => (
235+
<MaterialCommunityIcons name="account" color={color} size={26} />
236+
),
237+
}}
238+
/>
239+
</Tab.Navigator>
240+
);
241+
}
242+
```

docs/docs/guides/9-react-navigation.md renamed to docs/docs/guides/09-react-navigation.md

File renamed without changes.

‎docs/docusaurus.config.js‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,8 +78,6 @@ const config = {
7878
BottomNavigation: {
7979
BottomNavigation: 'BottomNavigation/BottomNavigation',
8080
BottomNavigationBar: 'BottomNavigation/BottomNavigationBar',
81-
createMaterialBottomTabNavigator:
82-
'../react-navigation/navigators/createMaterialBottomTabNavigator',
8381
},
8482
Button: {
8583
Button: 'Button/Button',
@@ -247,7 +245,7 @@ const config = {
247245
type: 'doc',
248246
docId: 'guides/getting-started',
249247
position: 'left',
250-
label: 'Docs',
248+
label: 'Guides',
251249
},
252250
{
253251
type: 'doc',

‎src/react-navigation/navigators/createMaterialBottomTabNavigator.tsx‎

Lines changed: 3 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -27,88 +27,6 @@ export type MaterialBottomTabNavigatorProps = DefaultNavigatorOptions<
2727
TabRouterOptions &
2828
MaterialBottomTabNavigationConfig;
2929

30-
// This is just Docusaurus can parse the type and show it in the docs
31-
export type Props = {
32-
/**
33-
* Event which fires on tapping on the tab in the tab bar.
34-
*/
35-
tabPress: { data: undefined; canPreventDefault: true };
36-
37-
/**
38-
* Event which fires on long pressing on the tab in the tab bar.
39-
*/
40-
onTabLongPress: { data: undefined; canPreventDefault: true };
41-
42-
/**
43-
* Title text for the screen.
44-
*/
45-
title?: string;
46-
47-
/**
48-
* Color of the tab bar when this tab is active. Only used when `shifting` is `true`.
49-
*/
50-
tabBarColor?: string;
51-
52-
/**
53-
* Label text of the tab displayed in the navigation bar. When undefined, scene title is used.
54-
*/
55-
tabBarLabel?: string;
56-
57-
/**
58-
* String referring to an icon in the `MaterialCommunityIcons` set, or a
59-
* function that given { focused: boolean, color: string } returns a React.Node to display in the navigation bar.
60-
*/
61-
tabBarIcon?:
62-
| string
63-
| ((props: { focused: boolean; color: string }) => React.ReactNode);
64-
65-
/**
66-
* Badge to show on the tab icon, can be `true` to show a dot, `string` or `number` to show text.
67-
*/
68-
tabBarBadge?: boolean | number | string;
69-
70-
/**
71-
* Accessibility label for the tab button. This is read by the screen reader when the user taps the tab.
72-
*/
73-
tabBarAccessibilityLabel?: string;
74-
75-
/**
76-
* ID to locate this tab button in tests.
77-
*/
78-
tabBarButtonTestID?: string;
79-
} & MaterialBottomTabNavigatorProps;
80-
81-
/**
82-
* A material-design themed tab bar on the bottom of the screen that lets you switch between different routes with animation. Routes are lazily initialized - their screen components are not mounted until they are first focused.
83-
*
84-
* This is a convenient wrapper which provides prebuilt [React Navigation's Bottom Tabs Navigator](https://reactnavigation.org/docs/bottom-tab-navigator/) integration so users can easily import it and use and don’t want to deal with setting up a custom tab bar.
85-
* :::info
86-
* To use `createMaterialBottomTabNavigator` ensure that you have installed [`@react-navigation/native` and its dependencies (follow this guide)](https://reactnavigation.org/docs/getting-started),
87-
* :::
88-
*
89-
* <div class="screenshots">
90-
* <img class="medium" src="screenshots/material-bottom-tabs.gif" />
91-
* </div>
92-
*
93-
* ## Usage
94-
* ```js
95-
* import * as React from 'react';
96-
* import { createMaterialBottomTabNavigator } from 'react-native-paper/react-navigation';
97-
*
98-
* const Tab = createMaterialBottomTabNavigator();
99-
*
100-
* function MyTabs() {
101-
* return (
102-
* <Tab.Navigator>
103-
* <Tab.Screen name="Home" component={HomeScreen} />
104-
* <Tab.Screen name="Settings" component={SettingsScreen} />
105-
* </Tab.Navigator>
106-
* );
107-
* }
108-
* export default MyTabs;
109-
*
110-
* ```
111-
*/
11230
function MaterialBottomTabNavigator({
11331
id,
11432
initialRouteName,
@@ -117,7 +35,7 @@ function MaterialBottomTabNavigator({
11735
screenListeners,
11836
screenOptions,
11937
...rest
120-
}: Props) {
38+
}: MaterialBottomTabNavigatorProps) {
12139
const { state, descriptors, navigation, NavigationContent } =
12240
useNavigationBuilder<
12341
TabNavigationState<ParamListBase>,
@@ -146,12 +64,9 @@ function MaterialBottomTabNavigator({
14664
);
14765
}
14866

149-
MaterialBottomTabNavigator.displayName = 'createMaterialBottomTabNavigator';
15067
export default createNavigatorFactory<
15168
TabNavigationState<ParamListBase>,
15269
MaterialBottomTabNavigationOptions,
15370
MaterialBottomTabNavigationEventMap,
154-
React.ComponentType<MaterialBottomTabNavigatorProps> /** Hack to sutisfies TS given the Prop type created for Docusaurus */
155-
>(
156-
MaterialBottomTabNavigator as React.ComponentType<MaterialBottomTabNavigatorProps>
157-
);
71+
typeof MaterialBottomTabNavigator
72+
>(MaterialBottomTabNavigator);

0 commit comments

Comments
 (0)