BottomTabBar & NavigationRail
The bar of an app's main destinations: along the bottom on a phone (BottomTabBar), down the side on a tablet or desktop (NavigationRail). Icons over labels, with count or dot badges, drawn as iOS's tab bar or Material 3's navigation bar. It draws the bar; your navigator, or a useState, shows the screen.
import { BottomTabBar, NavigationRail } from 'patine-ui';
<Box border radius="lg" style={{ width: '100%', maxWidth: 360, height: 300, overflow: 'hidden' }}> <Center fill> <Heading level={3}>{current.label}</Heading> </Center> <BottomTabBar items={TABS} value={tab} onValueChange={setTab} /> </Box>
Try the props
bottomInsetdesign<BottomTabBar items={tabs} value={tab} onValueChange={setTab} />
Example: a shop app
A shop's tab bar: Add to cart on the Shop tab raises the Cart tab's badge, and each tab keeps its own screen.
<Box border radius="lg" style={{ width: '100%', maxWidth: 380, height: 340, overflow: 'hidden' }}> <VStack gap="sm" padding="md" style={{ flex: 1 }}> {tab === 'shop' ? PRODUCTS.map((p) => ( <HStack key={p.name} justify="space-between" align="center"> <VStack> <Text weight="medium">{p.name}</Text> <Text size="sm" color="textSecondary">${p.price}</Text> </VStack> <Button size="sm" variant="outline" onPress={() => setCart((c) => [...c, p.name])}> Add to cart </Button> </HStack> )) : null} {tab === 'cart' ? ( cart.length ? ( <> {cart.map((item, i) => <Text key={i}>{item}</Text>)} <Button onPress={() => setCart([])}>Check out</Button> </> ) : ( <Text color="textSecondary">Your cart is empty.</Text> ) ) : null} {tab === 'search' ? <Text color="textSecondary">Search shirts, bags and hats.</Text> : null} {tab === 'account' ? <Text color="textSecondary">Signed in as [email protected]</Text> : null} </VStack> <BottomTabBar items={tabs} value={tab} onValueChange={setTab} /> </Box>
With React Navigation
Render it as the navigator's tabBar, and pass the safe area's bottom inset so it clears the home indicator:
<Tab.Navigator
tabBar={({ state, navigation }) => (
<BottomTabBar
items={state.routes.map((r) => ({ value: r.name, label: r.name, icon: ICONS[r.name] }))}
value={state.routes[state.index].name}
onValueChange={(name) => navigation.navigate(name)}
bottomInset={insets.bottom}
/>
)}
>
Pressing the selected tab calls onValueChange again, so you can scroll its screen to the top or pop it to its root, as iOS apps do.
NavigationRail
The same items down the side, for a tablet or a desktop window: swap it in for BottomTabBar when the screen is wide. header goes above the items, such as a menu button or a FAB.
<Box border radius="lg" row style={{ height: 320, overflow: 'hidden' }}> <NavigationRail items={TABS} defaultValue="mail" header={<Button size="icon" variant="secondary" accessibilityLabel="Compose"><Icon name="edit" /></Button>} /> <Box flex={1} padding="lg"> <Text color="textSecondary">Content</Text> </Box> </Box>
Designs
| Design | Look |
|---|---|
| brand | 64pt, a hairline on top, the selected icon and label in the primary color |
| iOS | UITabBar: 49pt, a hairline on top, small labels, the selected item tinted |
| Material 3 | Navigation bar: 80dp on a tonal surface, a 64×32 pill behind the selected icon, bold label |
| web | 56pt with a top border |
Accessibility
- A
tablistoftabs, the current one selected. Badges are read with the label: "Inbox, 3 new". - Each tab fills its share of the bar, well over 44pt. On the web, Tab reaches the bar and arrow keys move along it.
Props
Both take View props.
| Prop | Type | Default | Description |
|---|---|---|---|
items | { value, label, icon?, badge?, disabled? }[] | — | The destinations. icon is a node or ({ selected, color }) => node; badge a count or true for a dot. |
value | string | — | The selected item, controlled. |
defaultValue | string | the first item | The selected item when uncontrolled. |
onValueChange | (value: string) => void | — | Called when the user picks an item, also the selected one. |
bottomInset | number | 0 | BottomTabBar: space under the bar for the home indicator. |
header | ReactNode | — | NavigationRail: above the items. |
topInset | number | 0 | NavigationRail: space above, for the status bar. |
accessibilityLabel | string | 'Tabs' | Names the bar. |
theme, design | As every component. |