UNPKG

12.6 kBTypeScriptView Raw
1import * as React from 'react';
2import { TouchableWithoutFeedbackProps, StyleProp, ViewStyle } from 'react-native';
3import { IconSource } from './Icon';
4declare type Route = {
5 key: string;
6 title?: string;
7 icon?: IconSource;
8 badge?: string | number | boolean;
9 color?: string;
10 accessibilityLabel?: string;
11 testID?: string;
12};
13declare type NavigationState = {
14 index: number;
15 routes: Route[];
16};
17declare type TabPressEvent = {
18 defaultPrevented: boolean;
19 preventDefault(): void;
20};
21declare type TouchableProps = TouchableWithoutFeedbackProps & {
22 key: string;
23 route: Route;
24 children: React.ReactNode;
25 borderless?: boolean;
26 centered?: boolean;
27 rippleColor?: string;
28};
29declare type Props = {
30 /**
31 * 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.
32 *
33 * By default, this is `true` when you have more than 3 tabs.
34 * Pass `shifting={false}` to explicitly disable this animation, or `shifting={true}` to always use this animation.
35 */
36 shifting?: boolean;
37 /**
38 * Whether to show labels in tabs. When `false`, only icons will be displayed.
39 */
40 labeled?: boolean;
41 /**
42 * State for the bottom navigation. The state should contain the following properties:
43 *
44 * - `index`: a number representing the index of the active route in the `routes` array
45 * - `routes`: an array containing a list of route objects used for rendering the tabs
46 *
47 * Each route object should contain the following properties:
48 *
49 * - `key`: a unique key to identify the route (required)
50 * - `title`: title of the route to use as the tab label
51 * - `icon`: icon to use as the tab icon, can be a string, an image source or a react component
52 * - `color`: color to use as background color for shifting bottom navigation
53 * - `badge`: badge to show on the tab icon, can be `true` to show a dot, `string` or `number` to show text.
54 * - `accessibilityLabel`: accessibility label for the tab button
55 * - `testID`: test id for the tab button
56 *
57 * Example:
58 *
59 * ```js
60 * {
61 * index: 1,
62 * routes: [
63 * { key: 'music', title: 'Music', icon: 'queue-music', color: '#3F51B5' },
64 * { key: 'albums', title: 'Albums', icon: 'album', color: '#009688' },
65 * { key: 'recents', title: 'Recents', icon: 'history', color: '#795548' },
66 * { key: 'purchased', title: 'Purchased', icon: 'shopping-cart', color: '#607D8B' },
67 * ]
68 * }
69 * ```
70 *
71 * `BottomNavigation` is a controlled component, which means the `index` needs to be updated via the `onIndexChange` callback.
72 */
73 navigationState: NavigationState;
74 /**
75 * Callback which is called on tab change, receives the index of the new tab as argument.
76 * The navigation state needs to be updated when it's called, otherwise the change is dropped.
77 */
78 onIndexChange: (index: number) => void;
79 /**
80 * Callback which returns a react element to render as the page for the tab. Receives an object containing the route as the argument:
81 *
82 * ```js
83 * renderScene = ({ route, jumpTo }) => {
84 * switch (route.key) {
85 * case 'music':
86 * return <MusicRoute jumpTo={jumpTo} />;
87 * case 'albums':
88 * return <AlbumsRoute jumpTo={jumpTo} />;
89 * }
90 * }
91 * ```
92 *
93 * Pages are lazily rendered, which means that a page will be rendered the first time you navigate to it.
94 * After initial render, all the pages stay rendered to preserve their state.
95 *
96 * You need to make sure that your individual routes implement a `shouldComponentUpdate` to improve the performance.
97 * To make it easier to specify the components, you can use the `SceneMap` helper:
98 *
99 * ```js
100 * renderScene = BottomNavigation.SceneMap({
101 * music: MusicRoute,
102 * albums: AlbumsRoute,
103 * });
104 * ```
105 *
106 * Specifying the components this way is easier and takes care of implementing a `shouldComponentUpdate` method.
107 * Each component will receive the current route and a `jumpTo` method as it's props.
108 * The `jumpTo` method can be used to navigate to other tabs programmatically:
109 *
110 * ```js
111 * this.props.jumpTo('albums')
112 * ```
113 */
114 renderScene: (props: {
115 route: Route;
116 jumpTo: (key: string) => void;
117 }) => React.ReactNode | null;
118 /**
119 * Callback which returns a React Element to be used as tab icon.
120 */
121 renderIcon?: (props: {
122 route: Route;
123 focused: boolean;
124 color: string;
125 }) => React.ReactNode;
126 /**
127 * Callback which React Element to be used as tab label.
128 */
129 renderLabel?: (props: {
130 route: Route;
131 focused: boolean;
132 color: string;
133 }) => React.ReactNode;
134 /**
135 * Callback which returns a React element to be used as the touchable for the tab item.
136 * Renders a `TouchableRipple` on Android and `TouchableWithoutFeedback` with `View` on iOS.
137 */
138 renderTouchable?: (props: TouchableProps) => React.ReactNode;
139 /**
140 * Get label text for the tab, uses `route.title` by default. Use `renderLabel` to replace label component.
141 */
142 getLabelText?: (props: {
143 route: Route;
144 }) => string | undefined;
145 /**
146 * Get accessibility label for the tab button. This is read by the screen reader when the user taps the tab.
147 * Uses `route.accessibilityLabel` by default.
148 */
149 getAccessibilityLabel?: (props: {
150 route: Route;
151 }) => string | undefined;
152 /**
153 * Get the id to locate this tab button in tests, uses `route.testID` by default.
154 */
155 getTestID?: (props: {
156 route: Route;
157 }) => string | undefined;
158 /**
159 * Get badge for the tab, uses `route.badge` by default.
160 */
161 getBadge?: (props: {
162 route: Route;
163 }) => boolean | number | string | undefined;
164 /**
165 * Get color for the tab, uses `route.color` by default.
166 */
167 getColor?: (props: {
168 route: Route;
169 }) => string | undefined;
170 /**
171 * Function to execute on tab press. It receives the route for the pressed tab, useful for things like scroll to top.
172 */
173 onTabPress?: (props: {
174 route: Route;
175 } & TabPressEvent) => void;
176 /**
177 * Custom color for icon and label in the active tab.
178 */
179 activeColor?: string;
180 /**
181 * Custom color for icon and label in the inactive tab.
182 */
183 inactiveColor?: string;
184 /**
185 * Whether animation is enabled for scenes transitions in `shifting` mode.
186 * By default, the scenes cross-fade during tab change when `shifting` is enabled.
187 * Specify `sceneAnimationEnabled` as `false` to disable the animation.
188 */
189 sceneAnimationEnabled?: boolean;
190 /**
191 * Whether the bottom navigation bar is hidden when keyboard is shown.
192 * On Android, this works best when [`windowSoftInputMode`](https://developer.android.com/guide/topics/manifest/activity-element#wsoft) is set to `adjustResize`.
193 */
194 keyboardHidesNavigationBar?: boolean;
195 /**
196 * Safe area insets for the tab bar. This can be used to avoid elements like the navigation bar on Android and bottom safe area on iOS.
197 * The bottom insets for iOS is added by default. You can override the behavior with this option.
198 */
199 safeAreaInsets?: {
200 top?: number;
201 right?: number;
202 bottom?: number;
203 left?: number;
204 };
205 /**
206 * Style for the bottom navigation bar. You can pass a custom background color here:
207 *
208 * ```js
209 * barStyle={{ backgroundColor: '#694fad' }}
210 * ```
211 */
212 barStyle?: StyleProp<ViewStyle>;
213 style?: StyleProp<ViewStyle>;
214 /**
215 * @optional
216 */
217 theme: ReactNativePaper.Theme;
218};
219declare const _default: (React.ComponentClass<Pick<Props, "style" | "navigationState" | "renderScene" | "renderIcon" | "renderLabel" | "renderTouchable" | "getLabelText" | "getBadge" | "getColor" | "getAccessibilityLabel" | "getTestID" | "activeColor" | "inactiveColor" | "keyboardHidesNavigationBar" | "barStyle" | "labeled" | "sceneAnimationEnabled" | "onTabPress" | "onIndexChange" | "shifting" | "safeAreaInsets"> & {
220 theme?: import("@callstack/react-theme-provider").$DeepPartial<ReactNativePaper.Theme> | undefined;
221}, any> & import("@callstack/react-theme-provider/typings/hoist-non-react-statics").NonReactStatics<(React.ComponentClass<Props, any> & {
222 ({ navigationState, renderScene, renderIcon, renderLabel, renderTouchable, getLabelText, getBadge, getColor, getAccessibilityLabel, getTestID, activeColor, inactiveColor, keyboardHidesNavigationBar, barStyle, labeled, style, theme, sceneAnimationEnabled, onTabPress, onIndexChange, shifting, safeAreaInsets, }: Props): JSX.Element;
223 /**
224 * Function which takes a map of route keys to components.
225 * Pure components are used to minimize re-rendering of the pages.
226 * This drastically improves the animation performance.
227 */
228 SceneMap(scenes: {
229 [key: string]: React.ComponentType<{
230 route: Route;
231 jumpTo: (key: string) => void;
232 }>;
233 }): ({ route, jumpTo, }: {
234 route: Route;
235 jumpTo: (key: string) => void;
236 }) => JSX.Element;
237}) | (React.FunctionComponent<Props> & {
238 ({ navigationState, renderScene, renderIcon, renderLabel, renderTouchable, getLabelText, getBadge, getColor, getAccessibilityLabel, getTestID, activeColor, inactiveColor, keyboardHidesNavigationBar, barStyle, labeled, style, theme, sceneAnimationEnabled, onTabPress, onIndexChange, shifting, safeAreaInsets, }: Props): JSX.Element;
239 /**
240 * Function which takes a map of route keys to components.
241 * Pure components are used to minimize re-rendering of the pages.
242 * This drastically improves the animation performance.
243 */
244 SceneMap(scenes: {
245 [key: string]: React.ComponentType<{
246 route: Route;
247 jumpTo: (key: string) => void;
248 }>;
249 }): ({ route, jumpTo, }: {
250 route: Route;
251 jumpTo: (key: string) => void;
252 }) => JSX.Element;
253}), {}>) | (React.FunctionComponent<Pick<Props, "style" | "navigationState" | "renderScene" | "renderIcon" | "renderLabel" | "renderTouchable" | "getLabelText" | "getBadge" | "getColor" | "getAccessibilityLabel" | "getTestID" | "activeColor" | "inactiveColor" | "keyboardHidesNavigationBar" | "barStyle" | "labeled" | "sceneAnimationEnabled" | "onTabPress" | "onIndexChange" | "shifting" | "safeAreaInsets"> & {
254 theme?: import("@callstack/react-theme-provider").$DeepPartial<ReactNativePaper.Theme> | undefined;
255}> & import("@callstack/react-theme-provider/typings/hoist-non-react-statics").NonReactStatics<(React.ComponentClass<Props, any> & {
256 ({ navigationState, renderScene, renderIcon, renderLabel, renderTouchable, getLabelText, getBadge, getColor, getAccessibilityLabel, getTestID, activeColor, inactiveColor, keyboardHidesNavigationBar, barStyle, labeled, style, theme, sceneAnimationEnabled, onTabPress, onIndexChange, shifting, safeAreaInsets, }: Props): JSX.Element;
257 /**
258 * Function which takes a map of route keys to components.
259 * Pure components are used to minimize re-rendering of the pages.
260 * This drastically improves the animation performance.
261 */
262 SceneMap(scenes: {
263 [key: string]: React.ComponentType<{
264 route: Route;
265 jumpTo: (key: string) => void;
266 }>;
267 }): ({ route, jumpTo, }: {
268 route: Route;
269 jumpTo: (key: string) => void;
270 }) => JSX.Element;
271}) | (React.FunctionComponent<Props> & {
272 ({ navigationState, renderScene, renderIcon, renderLabel, renderTouchable, getLabelText, getBadge, getColor, getAccessibilityLabel, getTestID, activeColor, inactiveColor, keyboardHidesNavigationBar, barStyle, labeled, style, theme, sceneAnimationEnabled, onTabPress, onIndexChange, shifting, safeAreaInsets, }: Props): JSX.Element;
273 /**
274 * Function which takes a map of route keys to components.
275 * Pure components are used to minimize re-rendering of the pages.
276 * This drastically improves the animation performance.
277 */
278 SceneMap(scenes: {
279 [key: string]: React.ComponentType<{
280 route: Route;
281 jumpTo: (key: string) => void;
282 }>;
283 }): ({ route, jumpTo, }: {
284 route: Route;
285 jumpTo: (key: string) => void;
286 }) => JSX.Element;
287}), {}>);
288export default _default;